Gentoo Wiki:Contributor's guide

From Gentoo Wiki
Jump to:navigation Jump to:search

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

Warning
Some email providers can occasionally block the account creation confirmation email as spam. If not receiving the email, check the "spam" folder, but the email can sometimes be blocked even before that. Using an account with an alternate email provider can sometimes circumvent the issue. Please get in touch on #gentoo-wiki (webchat) if having issues creating an account. See the warning on the main page about the current issues with Gmail mail delivery.

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

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

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.

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.

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.

Refer to the help pages to learn about available formatting syntax. The wiki guidelines go into depth about how the wiki syntax should be used. 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, == 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.

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

Tip
For anyone starting to make somewhat regular contributions, please come join us on IRC: #gentoo-wiki (webchat). The web chat should work well for anyone not wanting to set up an IRC client. The channel can be quiet, but we will try to answer any questions the best we can.

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!

Troubleshooting

"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/<pagename>" (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.

See also