Gentoo Wiki:Contributor's guide

From Gentoo Wiki
Jump to:navigation Jump to:search

This page provides guidance for anyone interested in contributing to the Gentoo wiki, it aims to easily and quickly get people started with simple edits, and provides general editing advice. This guide is an indispensable starting point for making even minor changes to the wiki.

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.

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 fact based. The project is consensus based.
Spot a mistake, an omission? Please help out by correcting it! Making quick changes to the wiki is easy, even for a newcomer! It's a great way to contribute to the Gentoo project, and anyone can get started in minutes. Dive into editing right away, by checking out the getting started section.

Helping out on the wiki is a relatively easy way to get into contributing to the Gentoo project. No need to be a "Linux expert", anyone can create a wiki account, and even small changes are appreciated - even just correcting something noticed while reading the wiki.

For anyone wanting to pitch in, there are lists of simple changes waiting to be made, that nobody has has had the time to do yet. To your keyboards!

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.

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 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, and only then 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 trivial for any reader to improve the Wiki, at any time - and there is no reason to wait!

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, strive to write clearly and concisely, to add useful information, and it's difficult to go wrong!

Account in hand, 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!

Some email providers can occasionally block the account creation confirmation email as spam. If not receiving the email, check "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 with us on #gentoo-wiki (webchat) if having issues creating an account.

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, layout issues can be fixed by more experienced editors later. Start by making small edits to pages, to get a feel of how things are done.

Keep in mind that more experienced editors and administrators will often 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" ;).
Sometimes edits will be reverted, don't take offense, this is part of the process. Sometimes 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.

By preserving a history of every change, nothing can ever "break", so when something in need of improvement is identified, 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 when really aiming to improve things, it is more likely that a not so good edit will serve as a basis for improvement by another editor.

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.

When some type of special formatting is needed e.g. new headings or bold text, use wiki syntax or the buttons in the edit toolbar. See Help:Formatting for some of the common types of formatting used. There is also a visual editor available, which allows articles to be modified through an interface resembling a word processor.

Starting out, remember that there is an active community at work, with some having contributed extensively over years. Advice and edits from experienced contributors and administrators may not always be immediately clear, but there will usually be good reason. There are still some conventional ways of doing things that have emerged over the years that may not have been formalized or written down in the help pages, please be patient.

See the general editing advice section for practical information on editing articles. See the writing good articles section to learn how to contribute better content. See the areas for contribution section for edits that will be particularly helpful. See the further contribution section to go even deeper, and by all means check out the rest of this article as well.

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. The source editor should provide more precise control over layout.

Content is set out in the source editor by using wiki markup, for example by using several single quotes (') to mark bold or italic text, surrounding text with a set number of equals signs (=) to add headers, or beginning a line with an asterisk (*) to make bullet lists. See the formatting help page for a list of basic formatting syntax. The wiki guidelines go into more detail of how to use formatting on the wiki, and anyone making larger edits should read this article.

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 translation tags section on 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. Do not worry too much about the summary at first, 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 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.

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

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.

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.

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.

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 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 "<pagename>" (to be precise, anything containing "//", 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