Gentoo Wiki:Contributor's guide

This page Article description::provides guidance for community members who are interested in contributing to the Gentoo wiki, which aims to create some of the best Linux-related documentation available.

The editing help pages provide guidance for opening an account, and getting up and running doing edits. They have information about how to use the tools provided by the wiki, how to format articles, and how to accomplish specific tasks. This article deals more with the goals and motivations of the wiki, what can be done to help out, and provides general context and guidance to editors starting out.

Anybody who has searched the web for Linux-related concepts will surely have seen results from the Gentoo Wiki pop up regularly. The documentation on this wiki has relatively high visibility, but what goes on to create the content to the desired standard can seem relatively obscure. Writing documentation is just as an important part of the wiki as the documentation itself, and efforts to improve its contents are vital.

No need to be a "Linux expert" to help, anyone can create an account, and make changes in minutes - and some things are very simple to do.

How the wiki works and to what end
The Gentoo Wiki is a great tool for both Gentoo users and developers to collaborate on quality, up to date documentation.

The Wiki Project aims to promote a collaborative effort to distill the collective knowledge of the Gentoo community at large into clear, concise, useful documentation for the benefit of all. Developers of course have proficient knowledge of the software they write, but it can be difficult to commit time to both development work and writing complete, detailed documentation. The Wiki lets the community take an active role in maintaining documentation, allowing developers, documentation writers, users, and even just casual readers of the wiki to collaborate. Corrections, additions, and discussions about documentation all take place through the wiki.

Special Gentoo Project pages do exist for Gentoo developer-controlled documentation, but the majority of articles on the Wiki are editable by all.

No one user has the amount of time or knowledge necessary to document the details of every package, explain all possible troubleshooting steps, or provide meaningful guides for configuring each package. Aiming to provide the best Linux-related documentation available on the web requires a group effort. The Gentoo project is all about collaboration, and many, diverse people are coming together everyday to build it. The wiki is not the only tool to participate, there are the Gentoo IRC channels, forums, mailing lists, https://bugs.gentoo.org, to name just a few other fora!

Getting started
There are some simple ways for any wiki reader to improve the Wiki, at any time - and no reason to wait to start! It is very easy to edit the contents of a wiki. Account in hand, it only takes a few clicks: click the "'" page tab at the top of a page, make changes (edits) to the text, add a brief summary of the edit, and click the "'" button!

The number one rule of wiki editing, is to be bold. Dive in and make changes. Other wiki contributors can correct mistakes later, so have confidence, and give it a try! Try to write clearly and concisely. Aim to do something which improves the contents of the wiki. An edit might be to contribute whole paragraphs or pages full of information, or it could be as simple as fixing a typo or spelling mistake.

The driving force behind wikis is edits, and by preserving a history of every change, nothing can ever "break" or ruin things. When noticing anything that could be improved, do not be afraid to make an edit, no matter how small, and change it for the better! The worst possible thing that can happen is to have the edit undone by someone with more editing experience, but when really aiming to improve things, it is more likely that a not so good edit will serve as a basis for a better one by another editor.

For contributors who are beginners or do not know where to start, the easiest thing to do is proofread articles - and this can even be done during everyday usage of the wiki for reference. Typos, incorrect information, dead links, and other errors can be found by simply reading through the articles, and all that is needed to make a correction is an account that can be opened in seconds.

Asking for help or clarification on a portion of an article that is confusing can easily be done with the talk pages, and suggestions will be much appreciated there. If anything is wrong on an article, it is usually more constructive to just fix it, but mentioning it on a talk page is much better than nothing. Be sure to well describe where an issue is located, so that other contributors can easily find it.

Another easy way to start helping out is to create articles about individual software packages, following software article blueprints, to document packages that have not been previously documented. 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 can document the process for others in a Wiki article.

For contributors interested in writing entirely new articles or maintaining article standards see the Wiki Guidelines article. It contains the expected structure, formatting, and style standards for wiki contributors who make regular edits.

When some type of special formatting is needed e.g. new headings or bold text, do this using wiki syntax or the buttons in the edit toolbar. See Help:Formatting for some of the common types of formatting used.

By all means check out the rest of this article, there is nothing too hard, and many pointers to things that even new users can do.

Areas needing contribution
The first thing to do is just add a correction when coming across it - formatting, spelling, instructions - everything helps! Any knowledge that can be added is always good, and more so the more it can be useful to others!

A list of articles that have been requested, but do not yet exist can be found here. Even a skeleton "stub" article is a meaningful contribution, providing basic information, and more importantly, a basis for other editors to flesh out a subject.

Many articles need improvement in a specific area. An extensive list of pages marked with areas marked for improvement can be found by browsing the Todo category. This is a great way to help out!

Moving on
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 will be a great boon to the community. Help can be provided through the talk pages, on IRC, 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 and concise when providing assistance, explain reasoning in edit summaries.

Closing open discussions by replying to questions or implementing changes is a great way to move the wiki forward.

Keep an eye out for contributors who are abusing the system. Sometimes corrections are needed. Always respect for each other, but if necessary, get in touch with a Wiki administrator if conflicts cannot be resolved.

Strive to write good, clear and concise documentation, make good edits, and improve poor articles.

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

General editing advice
Edit wiki source just like in any modern text editor.

Before saving a change, a short note describing the changes that were made should be entered in the  box. Do not worry too much about the summary, or spend too much time thinking about it; it is simply a little description of what was changed e.g. "fixed typo" or "added more information about Larry the cow", and why the changes were made.

The summary gets stored alongside the edit, and allows other contributors to track changes in the wiki more effectively. Changes might not be obvious, so the goal of this field is to describe the change and the reason behind it at a glance. Check the "minor edit" box for small, incontestable changes.

Add the page to the user's watchlist by clicking the checkbox, to follow up on subsequent changes to the article.

It is a good idea to use the "" button to see what the change will look like, before saving. It is good to get into the habit of eliminating mistakes by using a preview before saving, rather than saving several minor corrections after an edit has been made.

Another option is the "" button which previews the differences between the existing version and the edited version. This feature can be very helpful when attempting to determine what information to include in the edit summary, since it provides an excellent contrast of the changes made.

Remember to discuss any changes that need to be coordinated with other editors, to ask for help, or to explain edits that could be misunderstood.

Writing good articles
As mentioned, always follow the Gentoo Wiki Guidelines. This document provides precise information on what good Wiki articles should look like. Understand the Gentoo Wiki's style, format, and structure.

Be familiar with the Wiki editing help guides, these provide comprehensive reference material for contributors who may be unfamiliar with Wiki editing or who are new to MediaWiki markup in general.

Structure articles in a clear and helpful way. Article Blueprints were created with the goal of saving contributors some of the effort in having to manually type out entire articles, and help the wiki maintain a consistent style and layout throughout. For article that don't have a corresponding blueprint, inspiration can be drawn from the structure of other articles on the wiki.

Becoming a skillful contributor means doing the research necessary to produce quality articles. A proficient contributor will look into why things work the way they work, and provide the theory along with the practice in their articles. Articles should presume the readers have little to no understanding of the software or hardware they are documenting. Skillful article creation takes time and effort, only practice will perfect.

For experiments the sandbox page may be used.

A bit of history
Before the Wiki, documentation was managed by developers, who wrote documentation in GuideXML format which was then converted to HTML and hosted as sub-pages on the main website. Developers often lacked the time to write documentation, and maintaining documents in this manner was burdensome and inconvenient. Soon there were not enough editors in the Documentation project to keep on top of Gentoo's documentation needs.

Only official developers could publish documentation, as higher privileges were needed in order to have documentation officially hosted. This prevented potential contributors from even starting to help.

In time, community-created Gentoo wikis began popping up all around the web. There were some in English and some in German, but none were officially endorsed by the Gentoo project as a whole. Over the years, many of these sites shut down, but wiki.gentoo.org has turned out to be a great tool to collaborate on the documentation of Gentoo, and of Unix-like systems in general!