Gentoo Wiki:Contributor's guide

This page Article description::provides guidance for anyone interested in contributing to the Gentoo wiki, to easily and quickly get started with simple edits. This guide is indispensable starting point to anyone making even minor changes to the wiki, and it will point to ways to move on to more advanced participation, where appropriate.

The Gentoo wiki project aims to create some of the best Linux and Unix(like) documentation available, all while - naturally - covering how to use and administer the Gentoo Linux OS.

Helping on the wiki is a relatively easy way to start contributing to the Gentoo project. No need to be a "Linux expert", anyone can create an account, and even small changes are appreciated - even just something noticed while reading the wiki. For anyone wanting to pich in, there are lists of simple changes waiting to be made, that nobody has has the time to do yet. To your keyboards!

How the wiki works and to what end
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. What goes on to create the content to the desired standard may be less up front, but the wiki is foremost a tool for writing and collaborating on documentation, and only secondarily a site for reading it. Improving the wiki's contents are its raison d'être - documentation used to be in static files, progress was slow, and collaboration laborious - the wiki was created to be able to work faster, better, and more - as a 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 - and more!

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
Just add a correction when coming across anything that can be improved! Fixing formatting, spelling, links, instructions, content - everything helps. Any extra knowledge is always good, especially anything likely to be of use to others.

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 flesh out a subject.

A list of pages marked as having areas that need improvement can be found by browsing the Todo category.

It is sometimes necessary to work out for oneself how to do certain things, and if any time is spent trying to get something to work on Gentoo, this could be a perfect candidate to add to the wiki! The same goes when having solved a particular issue, resolutions can be of valuable help to other users, and the troubleshooting sections can be a great place to add such information.

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!

"This action has been automatically identified as harmful" error
Sometimes, when trying to save changes to an article, an error that starts with "Error: This action has been automatically identified as harmful, and therefore disallowed" and finishes by mentioning an abuse rule: "Disable writing internal wiki links as external besides required". This error is shown in a large red box when trying to save an article, and will prevent any changes from being committed.

This error is the abuse filter triggering when trying to link to an internal wiki page in the style " https://wiki.gentoo.org/wiki/ " (to be precise, anything containing "//wiki.gentoo.org/", with one exception). This is to avoid anyone using absolute links to reference wiki articles, as this does not allow the wiki to track links properly.

If it is absolutely necessary to include  "https://wiki.gentoo.org/"  in the text of an article, the "https://" part can be put between    tags to avoid triggering the filter.