Gentoo Wiki:Contributor's guide

Wiki Help pages
Contributor's guide — Guidelines — Fixing errors howto
Editing pages — Talk pages — Formatting
Code of conduct — Wiki FAQ

Contributing to the wiki is easy! This guide 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!

Important
Please follow the code of conduct when engaging in all wiki activity. The wiki project aims to maintain a respectful, constructive environment - please be polite and considerate of other users. All wiki edits should be made in the spirit of moving the project towards the common goals. Documentation and discourse should be objective and rooted in fact. The project is consensus-based - please listen to the admins and more experienced editors and devs.

See also
See the help pages on editing, for comprehensive information on how to work with the wiki. The wiki Guidelines article in particular is essential reading, to learn how to properly write and lay out articles, for anyone making nontrivial changes. If specifically looking to fix an error on the wiki, what to do when noticing an error on the wiki could help.

Tip
To dive into editing right away, check out the getting started section.

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 #gentoo-wiki (webchat) channel - the answer to the "CAPTCHA" can even be provided, if needed, but be patient - replies can take time).

Note
If not receiving the account creation confirmation email, check the "spam" folder. If having any issues creating an account please get in touch on #gentoo-wiki (webchat) on IRC. We 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 about any issue to wiki@gentoo.org.

Once logged in with the new account, it only takes a few clicks to make a change: click the "Edit source" (or "Edit") button at the top of a page, make changes (edits) to the text, add a brief summary of the edit, and click the "Save page" 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, minor 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.

Tip
Keep in mind that when more experienced editors and administrators rework additions, this is not a criticism, simply part of the process. Think of edits to previous work as "how about this", rather than "that was wrong" ;).

Note
Remember that there is an active community at work, with some having contributed extensively over years - edits from experienced contributors and administrators may not always be immediately clear, but there will usually be good reason. Sometimes edits will be reverted, don't take offense, this is part of the process. It may be just that an edit is too far off usual practices - this doesn't necessarily mean that there is no value to a change, but the edit may need work, perhaps to follow the wiki guidelines more closely.

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.

Tip
Ask for help or clarification through the talk pages, which is where wiki-related discussion takes place. Suggestions will also be much appreciated on a talk page, though it is often more constructive to make a change directly to an article. Mentioning an issue, or pointing out an area in need of improvement on a talk page is still very useful though, and much better than nothing. Be sure to describe where an issue is located, so that other contributors can easily find it.

Note
Anyone editing wiki pages, please come join us on IRC on the #gentoo-wiki (webchat) channel! (The web chat should work well for anyone not wanting to set up an IRC client.) This is where the editors come to chat about the wiki and what is currently happening. Questions, comments, or suggestions welcome! The channel can be quiet sometimes, but everyone will try to answer any questions the best they can!

General editing advice

Screenshot of editing this page with the source editor.

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.

Note
Certain articles contain "translation tags", that look like <--T: 15-->. Do not edit, create, or unnecessarily delete or move these tags, they should stay with the content they were assigned to. See the section on translation tags about how to deal with these tags.

Before saving a contribution, a short note describing the changes that were made should be entered in the Summary: 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 Show preview 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 Show changes 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.

Important
Edits should preferably be short, so that glancing over the recent changes and the edit summary can give an idea of the reasoning behind them. It is usually preferable to make one edit per section at a time, if possible. An ideal edit often has a specific impetus to it, and makes clear in what way it makes things better. Other editors need to be able to understand why things were changed, to be able to decide if an edit should be kept or not.

Note
Some pages, such as the handbook or projects, may be protected, in which case they are not publicly editable. To get changes made to these pages, suggest the edits on the corresponding talk page.

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.

See also
Be sure to refer to the wiki guidelines for more information on how the syntax is used on the wiki. See the help pages to learn about formatting syntax, they go into depth about all available syntax.

Headings

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

Add more = signs to make secondary headings: === Heading 2 ===.

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: {{c|<command>}}.

Use {{Path|<path>}} 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 [[<pagename>]].

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: [[<pagename>|<label>]].

To make an external link, surrond the address in single square brackets [https://<URL>]. 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: [https://<URL> <label>].

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 <do x> to <achieve y>". 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.

Tip
Please don't let drafts languish in the User namespace. When work is no longer ongoing, and if an article has reached sufficient content to become at least a small stub, please move the article to the main namespace so that others may work to improve it. Aim to let others contribute to articles as soon as possible.

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.

See also
See common wiki tasks to help out for things that regularly need looking out for on the wiki.

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 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.