Gentoo Wiki:Contributor's guide
Contributor's guide — Guidelines — Fixing errors howto
Editing pages — Talk pages — Formatting
Code of conduct — Wiki project page — About Gentoo wiki — Wiki FAQ
Help improve the documentation! — Contributing to Gentoo
This article is about contributing to the documentation effort. For other ways to contribute to the Gentoo project, see contributing to Gentoo.
The Gentoo wiki project brings people together with the goal of creating the best documentation possible for Unix(like) OSs, not only for Gentoo users but for all users across the Internet. Contributing to documentation is easy with the wiki - this guide will help anyone quickly get started with simple edits, to begin improving articles in minutes!
Adding to and improving the documentation 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.
The majority of the documentation on the wiki is publicly editable, and is written by any users who can volunteer contributions. Please help to build the wiki: all corrections, additions, and useful changes benefit the free software community at large!
The Gentoo project needs help from its users. The help improve Gentoo by getting involved with documentation! page points to the areas where assistance is particularly useful.
Please, read on, and happy editing!
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, devs, and other editors.
The help improve Gentoo by getting involved with documentation! article explains how to best help improve the documentation. See the help pages 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 - anyone making nontrivial changes should give it a read. If specifically looking to fix an error on the wiki, the what to do when noticing an error on the wiki page can help.
For in-depth information about the project, see about the Gentoo wiki. The Gentoo wiki project page helps coordinate the effort to improve the documentation.
Getting started
It's easy for any reader to help improve the wiki - and there is no reason to wait! Just create an account to start editing pages, all that is required is a valid email address.
If having any issues creating an account, please get in touch in #gentoo-wiki (webchat) on IRC. People there 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 to wiki@gentoo.org. If not receiving the account creation confirmation email, check the "spam" folder.
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, etc., and can 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 and admins will provide leeway to new contributors, but will eventually make corrections to edits to bring them up to the quality requirements. Follow changes by other editors to learn the right way to write and format text.
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" ;).
Remember that there is an active community at work, with some having contributed extensively over years - the reasons behind edits from experienced contributors and administrators may not always be immediately clear, but there will usually be good reason. Sometimes edits will get reverted, but 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, so nothing can ever be "broken" by a change: 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.
Ask for help or clarification through the talk pages, which is where wiki-related discussion takes place. Suggestions can be made on talk pages, though it is nearly always much more constructive to directly make changes to articles. Bringing up an issue on a talk page is still better than nothing though (be sure to describe where an issue is located, so that other contributors can easily find it).
Anyone editing wiki pages, please come join us on IRC on the #gentoo-wiki (webchat) channel! 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
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 with a "WYSIWYG" editor resembling a word processor. The source editor should provide more precise control over layout though, and is what will be covered in this guide.
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.
Edits should preferably be short and change just one aspect of an article, so that glancing over the recent changes with the edit summary should give other editors a good idea of what changed and the reasoning behind the edit. 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.
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.
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.
Refer to the wiki guidelines for more information on how to best use syntax on the wiki. See the help pages for in-depth information about formatting syntax.
Headings
Add = signs around text on a line on its 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 equal 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 the {{Path}} template to indicate a path, or filename:
{{Path|<path>}}
Start lines with an asterisk * to create a "bullet list".
The guidelines have a section on inline layout elements providing many more elements that can be used to format content on the wiki.
Links
Links to other pages can be made by surrounding the page name with the {{Link}} template:
{{Link|<Page name>}}
To have a label that is different to the page name, the second argument can be adjusted:
{{Link|<Page name>|<label>}}
To make an external link, the address can simply be surrounded in single square brackets:
[https://example.com/...]
Always use the HTTPS protocol rather than HTTP, whenever possible.
To have an external link with a label, provide a label after the URI, separated by a "space" character:
[https://example.com/... <label>]
The "double square bracket"
[[Link]] syntax should be avoided, as it does not work well with the translation extension.The help page on links.
Writing good articles
The main resource for writing good quality articles are the Gentoo wiki guidelines. Editors making more than a few trivial edits should read and follow the guidelines. The guidelines provide precise information on what good articles should look like, laying out a standardized style, format, and structure.
Getting familiar with the wiki help pages will go a long way to help write better articles. These pages 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, and topics should be organized and classified into to-the-point sections that are easy to find.
Always aim for objectivity and facts. Never use articles to promote personal opinions or agendas.
As much as possible, organize articles by following the wiki's blueprints, for a consistent style across the wiki. Even for articles that don't fit to a preexisting blueprint, try to take inspiration from the blueprints. The blueprints are particularly useful when creating articles from scratch.
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 make 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 users.
For experiments, the sandbox page can 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 up the category listings with pages that other users can't contribute to.
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
See help improve Gentoo by getting involved with documentation! for areas that need attention. This section will provide a brief summary of that in-depth article.
During daily activity it is useful to check articles as they are read and used. Also, any setups that have to be figured-out for oneself are great candidates to add to the wiki.
One easy and useful activity is to proofread articles - and this can even be done during everyday-use of the wiki.
When having solved a particular issue, these resolutions could 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.
There are lists of pages marked as having specific areas in need of improvement in the Todo category.
A new page may be started for anything that could be useful to other Gentoo Linux wiki readers.
Closing discussions 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. Categorizing discussions helps important discussions get seen.
See also
- Contributing to Gentoo — explains how users can contribute to the development of Gentoo
- Gentoo_Wiki:FAQ — a collection of common questions about the Gentoo wiki, the documentation contained within, and editing the wiki, along with their corresponding answers
- Gentoo_Wiki:Guidelines — provide writing-conventions and layout-schemes that aim for a consistent and professional presentation across all of the wiki's diverse articles
- Help:Contents — provide useful information about using the Gentoo wiki
- Help improve Gentoo by getting involved with documentation! — the areas where anyone can help improve the documentation for the benefit of both Gentoo users and unix(like) users across the Internet
- Project:Council/Code_of_conduct — describes Gentoo's Code of Conduct for public communication fora, as well as the action taken should it be broken.
- Project:Wiki — coordinates contributors to help make it easy to write the best possible documentation both for Gentoo users, and for the Unix(like) community at large
- What to do when noticing an error on the wiki — what to do when noticing an error on the wiki, to get things fixed