Gentoo Wiki:Contributor's guide

Contributing to the wiki is easy! This guide Article description::aims to help quickly get started with simple edits, so anybody can be making great additions to the wiki in minutes.

The Gentoo wiki project brings people together with the goal of creating the best Linux and Unix(like) documentation available, while covering in detail how to use and administer the Gentoo Linux OS. All editors are volunteers, and any help is much appreciated, to the benefit of the free software community at large.

Adding to and improving the wiki is one of the easiest ways to start contributing to the Gentoo project. No need to be a "Linux expert", anyone can make a difference! Even small changes are appreciated, like correcting a mistake noticed while reading the wiki.

Please, read on, and happy editing!

Introduction to the Gentoo wiki project
Anybody who has searched the web for Linux-related concepts will probably have seen results from the Gentoo wiki pop up - the documentation on this wiki often has relatively good visibility. What goes on to create the content to the desired standard may be less up front, but the wiki is first of all a tool for writing and collaborating on documentation, as well as a site for reading it.

The Wiki project is a collaborative effort to distill the collective knowledge of the Gentoo community at large into clear, concise, useful documentation, for the benefit of all.

The Wiki lets the community take an active role in helping to maintain documentation. Developers have proficient knowledge of the software they write, but it can be difficult to commit time to both development work and to writing complete, detailed documentation. The wiki was put in place as an efficient solution for developers, documentation writers, users, and even just casual readers, to work together on up to date documentation. It allows fast paced progression, while aiming for the highest standard.

The Gentoo project is all about collaboration, and many, diverse people are coming together everyday to build it. No one user has the amount of time or knowledge necessary to document the details of every package, to explain all possible troubleshooting steps, or to provide meaningful guides for each notable piece of software. Working to provide the best Linux-related documentation available requires a group effort, and the wiki has turned out to be an excellent tool to that end.

Remember, there are other mediums through which to participate, such as the Gentoo IRC channels, forums, mailing lists, Bugzilla - and more!

Getting started
It is very simple for any reader to improve the wiki, at any time - and there is no reason to wait! To start, just create an account (in case of any problem creating an account, log on to the channel - the answer to the "CAPTCHA" can even be provided, if needed, but be patient - replies can take time).

Once logged in with the new account, it only takes a few clicks to make a change: click the "Edit source" (or "'") button at the top of a page, make changes (edits) to the text, add a brief summary of the edit, and click the "'" button - done!

An edit can add information, make a correction, provide a useful link, and may be as simple as fixing a typo. Aim to do something which improves the contents of the wiki: try to write clearly and concisely, and to add useful information - with that, it's difficult to go wrong!

Be bold - other wiki contributors can correct mistakes later, so have confidence. Dive in and make changes - the rule is that changes must make an article better than before. Starting out, formatting and language issues can be left to be fixed by more experienced editors: getting information into the wiki is key, layout can be adjusted later.

Start by making small edits to pages, to get a feel of how things are done. Experienced editors should provide leeway to new contributors, and will correct additions, so the right way to write and format text can be learned along the way, to some extent.

The wiki preserves a history of every modification, consequently nothing can be "broken" by a change, so do not be afraid to make an edit. The worst thing that can happen is to have the edit undone by someone with more editing experience, but often an edit that needs work will serve as a basis for improvement by another editor.

See the next section, general editing advice, for practical information on editing articles - and by all means check out the rest of this article as well.

General editing advice


Edit wiki source just like in any modern text editor, by clicking the Edit source button (or just Edit if so configured in the preferences). There is also a visual editor that is opened with the Edit button, when activated in the preferences, which allows articles to be modified through an interface resembling a word processor. The source editor should provide more precise control over layout, and is what will be covered in this guide.

Before saving a contribution, a short note describing the changes that were made should be entered in the  box. Just quickly describe what was changed, and why the changes were made, e.g. "fixed typo" or "added more information about Larry the cow".

Check the "minor edit" box for small changes, that couldn't reasonably need any further modification. Add the page to the watchlist by clicking the Watch this page checkbox, to be notified of subsequent changes to the article.

It is a good idea to use the  button to see what the change will look like before saving - get into the habit of eliminating mistakes by using the preview, to help avoid the need for corrections after an edit has been made.

Another option is the  button which highlights the differences between the existing version and the edited version. This feature can be helpful when attempting to determine what information to include in the edit summary.

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

Wiki markup primer
Content is set out in the source editor by using wiki markup, for example to add headings, links, or to make text bold or italic. There is a toolbar that can help when starting out, it can be toggled in the preferences. For those who prefer a "WYSIWYG" approach there is the visual editor, but that will not be covered here.

This section will very succinctly present some of the most common syntax, just as a quick indicator of basic usage, to give a feel of what the markup means, and to allow some quick edits.

Headings
Add  signs around text on a line on it's own to make headings. For example,  to make a main title.

Add more  signs to make secondary headings:.

Add more equals signs for smaller level headings. A "level zero" heading with just one equels sign is never used on the wiki.

Text formatting
Use two single quotes  around text to make it italic.

Use three single quotes  to make text bold.

Use the "c" template around commands that are to be typed into the terminal:.

Use  to indicate a path, or filename.

Start lines with an asterisk  to create a "bullet list".

Links
Links to other pages can be made by surrounding the page name with double square brackets.

To have a label different than the page name shown to the reader, provide a label after the link name, separated by a "pipe" character:.

To make an external link, surrond the address in single square brackets. Use the HTTPS protocol rather than HTTP, if possible.

To have an external link with a label, provide a label after the URI, separated by a "space" character:.

Writing good articles
For anyone making more than trivial edits, the first thing to do to make sure articles are up to minimum standards, is to always follow the Gentoo wiki Guidelines. This document provides precise information on what good articles should look like, laying out proper style, format, and structure.

Be familiar with the Wiki editing help pages: these provide comprehensive reference material for contributors.

Structure articles in a clear and helpful way, and write in a neutral style. Refer to "the user", and not "you". Stay on topic: the wiki is for documenting Gentoo, and relevant Linux and Unix(like) subjects, it is not a place to promote personal opinions or agendas - aim for objectivity and facts.

There are article blueprints to help the wiki maintain a consistent style and layout throughout, and to make creating some articles from scratch a little easier. For articles that don't have a corresponding blueprint, inspiration can be drawn from the structure of preexisting articles.

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 do, and provide the theory along with the practice in their articles. Articles should presume that readers have little to no understanding of the software or hardware being documented. Skillful article creation takes time and effort, only practice will perfect.

If something is known to work locally, but generalization isn't guaranteed, use the conditional mood: "users may find that they have to to ". Of course, only add information to the wiki that will be of general interest to other uses.

For experiments, the sandbox page may be used. The User namespace may be used to begin draft articles. Please do not apply categories to articles in the User namespace - they clutter the categories up with pages that other user's can't contribute to.

Areas for contribution
For contributors who are beginners, or do not know where to start, the easiest thing to do is to proofread articles - and this can even be done during everyday use of the wiki.

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

There are lists of pages marked as having specific areas in need of improvement in the Todo category.

Another easy way to start helping out is to create articles about individual software packages of particular interest, following the software article blueprints. 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 - see starting a new page.

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.

Using Gentoo, it will sometimes be necessary to work out for oneself how to do certain things. If any time is spent setting up something specific, 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. After asking for support, it is particularly useful to contribute solutions back to the wiki, to the benefit of users, and so that people providing support might avoid future requests for the same issue.

Closing discussions (see the list of open discussions), for example after replying to a user's question or integrating proposed changes to the wiki, is a great way to contribute to the Gentoo wiki! Discussions are a way of making propositions and decisions about wiki contents, so they are best resolved in a timely manner, which will keep things more focused.

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 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 when providing assistance, and explain reasoning in edit summaries.

Following recent changes provides valuable information about what is going on on the wiki. Watch for changes to important articles, and lookout for any 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.

Thank others in the community (especially new contributors) for their contributions: everyone enjoys being appreciated for their work. This can be done via the ' link, 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.

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
When trying to save changes to an article, the following error may appear, and will prevent any changes from being committed : Error: This action has been automatically identified as harmful, and therefore disallowed. If you believe your action was constructive, please inform an administrator of what you were trying to do. A brief description of the abuse rule which your action matched is: Disable writing internal wiki links as external besides required

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.