Gentoo Wiki:Contributor's Guide

This contributor's guide provides instructions for users who are interested in making the Gentoo wiki the best Linux-related wiki on the web. It introduces potential Wiki contributors to the concepts needed in order to write good articles and details how to interact with the Wiki community as a whole.

Concepts

Many have queried in a favorite search engine about a Linux-related concept and have seen the Gentoo Wiki (or some other form of Gentoo-related documentation) appear near the top of the search results. Some have read wonderful (or perhaps terrible) articles on the Wiki and have gleaned helpful information. Few consider themselves up to the the task of writing documentation. Nevertheless, documentation must get written so that Linux users from all distributions will have quality reference material. Not everyone needs to be a "Linux expert" to help with documentation efforts on the Gentoo Wiki. Details on how every reader can help with the Gentoo Wiki project have been recorded in the sections below; however, please read this article in its entirety.

As mentioned above, this contributor's guide has been written for those who have an interest in helping the Gentoo Wiki become the greatest Linux Wiki on the web. All who are involved in the Gentoo project are glad to have the concerted efforts of the community in producing quality documentation here on the Wiki.

Documentation in the past

Before the Wiki, documentation was left up to a team of developers who wrote documentation in GuideXML format which was then converted to HTML and hosted as sub-pages on the main website. Maintaining documentation in this manner was burdensome and inconvenient for the developers. After some time of (successful) documentation there was an insufficient amount of editors and authors in the Documentation project to stay on task with Gentoo's documentation needs. After a while longer there were not many developers left who had the knowledge of GuideXML or the time required to write documentation. Soon Gentoo lagged behind because it took a great effort and there were not many around who could do the work.

Besides the difficulty that went in to the formatting, the documentation had to be published by an official developer; contributors could not simply write an article and publish it on Gentoo infrastructure themselves. This created another bottleneck for documentation: higher privileges were needed in order to have documentation officially hosted.

It is no wonder that, after even more time, many 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.

Documentation today

In contrast to the old way documentation was handled, the Gentoo Wiki is truly propelled by both the users and the developers of Gentoo. One of the hopes of the Wiki Project is to obtain a collaborative effort in summarizing the collective knowledge of the Gentoo community at large. Although developers tend to know a lot, especially in their areas of contribution, it can be difficult for them to maintain their current developer tasks while at the same time write documentation. The Wiki opens the door for the community to take an active role in maintaining documentation, making corrections, and having discussions about existing documentation. If an article has been poorly written, the community can make corrective edits or write entirely new articles without the help of a member of the Gentoo infrastructure team.

Special Gentoo Project pages do exist for Gentoo developer-controlled documentation; however, the majority of articles here on the Wiki are editable by the other smarties: the community of Gentoo.

The wiki is helpful

Giving the Gentoo community a simple way to add documentation and do translation work is helpful for a plethora of reasons!

No one user has the amount of time or knowledge necessary to document minute details of every package, explain all possible troubleshooting steps, or provide meaningful guides for configuring each software set;
Being a modular and flexible distribution, Gentoo needs the help of many in order to prosper and grow;
The Gentoo project loves to see users helping users. This goal can be obtained through several mediums including the Gentoo IRC channels, forums, and mailing lists, but we really hope the community will focus on writing articles for long-term effectiveness here on the Wiki!

Who can help

Having best Linux-related documentation available on the web requires a group effort. There are simple ways Wiki readers and contributors can improve the Wiki every time it is used. Ways to help can be divided into two separate "levels" depending on how much experience editing the Wiki the contributor has obtained. For the purpose of this guide the term "Padawan" will be used to refer to those with only a little contributing experience. The term "Apprentice" will be used to refer those who have been helping for a while and are comfortable with what needs to happen for continual Wiki improvement.

Padawans

For contributors who are beginners or not do know where to start, the easiest thing to do is proofread articles. Typos, incorrect information, dead links, and other errors are found by simply reading. After an error has been discovered, Padawans can can create an account (if they do not have one) and fix the error.

The following bullet points are some ways Padawans can contribute in order to make the Wiki better:

Be bold: do not be afraid to make an edit! The worst that can happen is to have the edit undone by someone with more editing experience.
Ask for help or clarity on a portion of the article that is confusing. Others on the Wiki can use a Padawan's input to fix and clarify parts of articles that may be confusing or poorly written. Discussion (Talk) pages should be used for questions or clarifications. It is extremely helpful for Apprentices to have good suggestions!
- Those who have knowledge to fix errors, please do take initiative to fix things. If an error is replaced with another error at least there was an attempt to make a correction. Errors will eventually get fixed whether Padawans do them or not; however these are the first steps in becoming a Apprentice contributor.
- Those who do not know how to fix issues, but know that something is wrong, leave a comment on the article's associated discussion page (sometimes called talk pages). Be sure to do well describing where the issue is located so that Wiki contributors can easily find it. Once the claim is verified a fix can be made. Remember to leave a signature so that others can tell who wrote the comment and how long it has been since it was written.
Learn how to write good articles. See below for more details.
Use the 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. If a Padawan feels comfortable installing, configuring, and using a certain software package then they are more than capable of documenting the process for others in a Wiki article. If it hasn't been done yet, document things you are good at, leave the things you lack knowledge on to someone else.

Apprentices

Those who have been contributing for a while (you know who you are) can help newcomers to the Wiki and continue to improve yourselves in the following ways:

Be helpful and available to assist others (especially Padawans) when assistance is needed. This can involve helping them with correct formatting or pointing them to appropriate information. Remember what it was like when you first started; it can be intimidating to ask for help, especially if someone is sarcastic or downright rude. Try to be friendly and direct when providing assistance.
Help facilitate conclusions on open discussions. When Padawans ask for input or make suggestions help guide them to solutions.
Keep an eye out for contributors who are abusing the system. Sometimes corrections are needed. Speak the truth, but with respect for each other, and as much as it depends on you live at peace with other contributors. If necessary get in communication with a Wiki administrator if conflicts cannot be resolved.
Be a positive example to others on the Wiki. Write good documentation and make good edits. Others will learn to respect an Apprentice's input and suggestions if they see solid work has been done.
- An Apprentice contributor has an eye for making poor articles into good articles. Apprentices are wise in the ways they interact with Padawans, knowing when to restructure or move an article. They also are wise in the ways they interact with others on the Wiki.
Thank others in the community (especially new contributors) for their contributions. Everyone enjoys being appreciated for their work. This should be done via the Gratitude section below, on a user's talk page (be sure to leave a signature), or via the #gentoo-wiki channel on IRC.

Writing good articles

The only way Padawans can obtain Apprentice status is by practice (practice takes time). As a Padawan gathers experience by making edits, asking questions, and fixing errors they should naturally begin to see distinctions between poorly written and well written articles. Over time they learn the skill of writing good articles.

There are a few more documents that should be briefly covered for those interested in the role of Wiki contributor. The following documents will save time and increase effectiveness by providing references to the tools that should be in each contributor's toolbox.

Wiki guidelines

Gentoo Wiki Guidelines — For those who have not read the Wiki Guidelines, please start here. This content provides precise information on what good Wiki articles should look like. Your goal in reading the Guidelines should be to understand the Gentoo Wiki's style, format, and structure. When this Contributor's Guide and the Wiki Guidelines have been fully read contributors will have obtained a solid conceptual footing for producing good articles.

Editing specifics

Wiki editing help — These articles provide comprehensive reference material for contributors who may be unfamiliar with Wiki editing or who are new to MediaWiki markup in general. Along with the Guidelines listed above, these articles can be used mostly as reference materials.

Rapid article production

Article Blueprints — These "blueprints" have been created with the goal of saving contributors some of the effort in having to manually type out entire articles. They provide rough outlines of how articles of certain categories should look and can save a lot of time since they provide basic structure; it is always easier to delete unnecessary text than to type out text that is missing. Simply copy the code to a new article and start filling in the blanks with the pertinent information.

Skillful article creation

Becoming a Apprentice contributor means doing the research necessary in order to produce skillfully written 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. These articles should presume the readers have little to no understanding of the software or hardware they are documenting. The article will teach the readers the tricks to becoming an expert user of the software.

Skillful article creation takes time and effort.

Contributing

Requested articles

A list of articles that have been requested, but have not been written can be found right here. Wiki contributors are welcome to research each topic or package and write helpful documentation. We look forward to seeing your contributions.

Todo category

There are many articles that need improvement in some fashion. An extensive list can be found by browsing the Todo category. Feel free to improve things!

Gratitude

When a user has made a helpful edit it is considered good etiquette to show appreciation by saying thanks. A Gentoo wiki account must be created and a user must be signed-in before the the Thank link will be visible. Thank can be found on the article's Revision history page (click More → History then find the Thanks link next to the specific revision).

Communication

Contributors who need help should be willing to ask for help! It is likely you will quickly find someone who will be able to assist you in the #gentoo-wiki channel on Freenode IRC. See the IRC guide for help on getting an IRC client connected to the Freenode network and into the #gentoo-wiki channel.