Help improve Gentoo by getting involved with documentation!

Wiki Help pages
Contributor's guide — Guidelines — Fixing errors howto
Editing pages — Talk pages — Formatting
Code of conduct — Wiki project page — About Gentoo wiki — Wiki FAQ
Help improve the documentation! — Contributing to Gentoo

Gentoo needs help! It is built by volunteers and requires constant work. Gentoo's documentation is no exception, though compared to much of Gentoo it is an area that is really easy to start participating in. Every little contribution gradually improves the OS for everyone - so please, start helping out today!

Editing documentation really is one of the easiest ways to start contributing to the Gentoo project, and the majority of the documentation on the wiki is publicly editable. Contributors don't have to be "Linux experts", everyone who can type at a keyboard has the potential to help out! Even small changes are appreciated, like fixing a typo, a link, or some other little mistake.

This article aims to show the areas where anyone can help improve the documentation for the benefit of both Gentoo users and unix(like) users across the Internet. To learn how to easily edit wiki pages, check out the contributor's guide - it's the most important document for getting started.

Gentoo is a large and mature project built by volunteers from all over the world. Each contributor has their own story of how they discovered Gentoo, adopted it, and moved on to helping out the community by contributing (even devs start somewhere). Everyone here loves getting a bit more help - start your journey today!

Tip
If having any issues creating an account, please get in touch in #gentoo-wiki (webchat) on IRC. People there can even provide the answer to the "CAPTCHA" to anyone having difficulty. Please be patient on the channel, replies can take time: stay connected waiting for a response, as people may be away from keyboard or even in different time zones. If a solution cannot be found in IRC, try sending an email to wiki@gentoo.org. If not receiving the account creation confirmation email, check the "spam" folder.

Note
The wiki is light and nimble: if you see something that needs fixing and have the confidence to sort it out, please feel free to just create an account and click the "Edit" button! This article goes into some detail about what readers can do to help out, but it's more for inspiration than required reading. The wiki is about being bold, and the other editors and readers are here to check new changes. When diving in like this though, the contributor's guide might still prove invaluable.

See also
As previously mentioned, the contributor's guide is the place to learn how to start editing articles. The guidelines explain how to make good edits, and the help pages provide comprehensive documentation on editing articles. For anyone here because of an error or other issue noticed in the docs, the what to do when noticing an error on the wiki page can help. See the about Gentoo wiki page for basic information on how the project works. Remember that there are even more ways to contribute to Gentoo.

Fix as you go!

Most Gentoo users will make use of the documentation during day to day operation. Invariably this means stumbling on sections that are unclear, incomplete, wrong, outdated, badly worded, or just sub-optimal in some way.

While this can be frustrating, it can also be seen as a chance to improve things for other readers. Whenever you see anything like this that can be improved, please do fix it for everybody.

The wiki is a two way street - it's not just meant for reading docs, it's also there to help make them better. Readers should absolutely use it to its full potential!

Using Gentoo, it will sometimes be necessary to figure out for oneself how to accomplish certain setups. When any time is spent working out something specific, this is a perfect candidate to add to the wiki so that others can benefit from the work!

Tip
Typos, spelling, incorrect information, dead links, formatting, and other errors can be found by simply reading through the articles - change anything that can be improved, especially things that are likely to be of use to others!

Explore and enhance

One of the most useful things anyone can do for the wiki is to just visit any page and give it a quick proof-read. Even with just a little experience, issues will often stand out and this creates the chance to fix things.

Of course, checking out the "core" Gentoo documentation (Portage, OpenRC, core system docs, etc.) will provide good potential to improve things the most for the most people. On the other hand, checking over less-visited pages is an important part of making sure issues don't get missed.

One step better is of course to actually try out the instructions from an article - and this in fact is a pretty important thing to do for anything that seems like it could be a little "off".

Document solutions, so that the community only has to troubleshoot once

When issues are solved on IRC, in the forums, or elsewhere on "the Internet", that is valuable work that will be of great interest to anyone else running into the same problem. The place that this information can most benefit users is of course the documentation, here on the wiki.

Forum threads often have to be found and interpreted, and this has to be done by each user who comes across the issue. Once a solution is arrived upon however, resuming it and copying that to the right place on the wiki can be a massive help to everyone who needs it.

With IRC, the benefit of transferring information to the wiki should be even more obvious, as IRC conversations are largely ephemeral. One thing to consider is to at least copy interesting troubleshooting sessions to wiki article talk pages so that information is not lost for others.

Tip
The "troubleshooting" sections can be a useful place to put solutions to issues that users have discovered.

Follow recent changes

Following recent changes provides valuable information about what is going on on the wiki. Watch for changes to important articles, and lookout for any errors or problematic edits.

Beware of people abusing the system, which can unfortunately occasionally happen. Spamming, or third parties trying to subvert the wiki to promote their products, should be quickly reverted. If necessary, get in touch with a wiki administrator, if conflicts cannot be resolved.

Tackle todo tasks

The central hub for requested work is the todo category. Check out that page for sections of the wiki that have been flagged as requiring attention.

There are also the specific pages that have been marked with the {{Todo}} or {{InfoBox todo}} templates: Category:Todo articles.

It's always useful to add any useful todo items to a page using these templates. Please add these templates when noticing anything missing or that needs changing, if the work cannot be done right away.

Start new articles

There is always room for new articles on useful concepts, packages, or procedures - feel free to start a new page for anything that could be useful to other Gentoo Linux wiki readers.

Articles about individual software packages of particular interest, following the software article blueprints, can be particularly useful. There are 10,000+ packages in the official Gentoo repository, many of which do not have corresponding articles on the Wiki. Anyone having installed, configured, and used a package of note can document the process for others in a wiki article.

A list of articles that have been requested, but do not yet exist, can be found on the requested articles page.

Even a skeleton {{stub}} article is a meaningful contribution - providing basic information, and more importantly, a basis for other editors to build out a full article.

Join the #gentoo-wiki IRC channel

Please come join us on IRC in the #gentoo-wiki (webchat) channel! This is where contributors come to chat about documentation and current wiki activity. Questions, comments, or suggestions welcome!

The channel can be quiet sometimes, but everyone will try to answer questions the best they can. Remember that participants are from across the globe, so people will be on different time zones. Be prepared to stay connected at least for a few hours in case no one is around currently.

The topic is of course "editing documentation and how to use the wiki". For off-topic discussion see #gentoo-chat (webchat), and for general Gentoo support see #gentoo (webchat).

Note
Anyone editing wiki pages, please do come join us in #gentoo-wiki (webchat). It can be very useful to be able to get in touch quickly through the IRC channel to ask questions as edits are being made.

Tip
The web chat accessible through the links above should work for anyone not wanting to set up an IRC client.

Important
The wiki IRC channel is about editing documentation on the wiki. For general Gentoo support, such as installation advice, usage issues, bugs, etc., please get in touch with the support community (#gentoo (webchat)), not the wiki team.

Please follow the code of conduct in the -wiki channel. The wiki project aims to maintain a respectful, constructive environment - please be polite and considerate of other users.

Further contribution

Once familiar with editing, assisting other users (especially new users) can be particularly productive. Learning from each other will propel the wiki forward, and helping to get new contributors on board is great for the community.

Help can be provided through the talk pages, on #gentoo-wiki (webchat) , and especially - following the "wiki way" of working - through edits: correcting, adding formatting, links, references or complimentary information to recent edits. Try to be friendly when providing assistance, and explain reasoning in edit summaries.

Anyone who writes both English and a foreign language can help the community out by translating documentation on the wiki.

Thank others in the community (especially new contributors) for their contributions: everyone enjoys being appreciated for their work. This can be done via the Thank link, found on an article's Revision history page (click More→History, then find the Thank link next to the specific revision). Thanks on a user's talk page (be sure to leave a signature), or via the #gentoo-wiki (webchat) channel on IRC will surely also be appreciated.

Common wiki tasks to help out

This is a list of recurrent-tasks on the wiki that are required to keep article quality as high as possible for readers. The team of volunteer editors often has a lot to do, so any help here is really appreciated.

Make articles conform to the guidelines

It's great to have useful content, but for readability and coherence across the wiki, articles should also conform to the guidelines. For users starting out, or who have not yet read it, please do read the guidelines - it's what lets our documentation form a consistent-whole across the wiki.

Adapting content to the guidelines can involve adding appropriate formatting-elements (such as {{C}}, {{Cmd}}, <var>cow</var>, etc.), adjusting writing style, adding lead-in sentences, etc.

Sometimes, an article will need rewording to avoid first and second person writing. Using a search function to go over the article and locate words such as "you", "your", "I", "we", "our", "one", etc. can be helpful.

Some common constructs and example replacements:

"you can do X to..." -> "X can be done to...", "doing X is an option to..."
"now you should do X" -> "do X"
"edit your config file" -> "edit the config file"

Make sure pages follow blueprints

Some articles such as those concerning a piece of software or hardware should conform to blueprints.

Add sections with appropriate content where useful - don't add sections just to hold to the template, the content must be of particular value for the article, otherwise sections from the blueprint should be omitted. Don't add empty sections.

Rename any sections that have content corresponding to a blueprint section but have used a different naming scheme.

Reorder sections so that they are in the same order as in the blueprint. Reorder the InfoBox items also, if necessary.

Even articles that don't have explicit blueprints should follow the "spirit" of the blueprints.

Reply to, categorize and close discussions

It's very useful to reply to discussions if possible, and even better to be able to categorize and close them. Discussions are used to make decisions about wiki contents, so closing them as soon as possible will invariably help move the documentation forwards.

Often, new users, and sometimes even more experienced ones, don't format talk pages properly. If needed, move new sections to the bottom of the page, new comments to the bottom of each section, indent each new comment properly, and add {{Unsigned}} if needed. Make sure there is a {{Talk}} template for each section, and a {{Talk page}} template at the top of the page.

Tag articles with maintenance templates

Some pages need work, or merit warning readers. Use the maintenance templates to mark articles accordingly.

Fix links

There is a nascent effort to detect and fix links across the wiki.