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, to easily and quickly get started with simple edits. 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.

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 fact based.
Tip
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 going straight to the getting started section.

Helping out on the wiki is a relatively easy way to start 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 the time to do yet. To your keyboards!

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

How the wiki works and to what end

Anybody who has searched the web for Linux-related concepts will surely have seen results from the Gentoo Wiki pop up regularly - the documentation on this wiki has relatively high visibility. What goes on to create the content to the desired standard may be less up front, but the wiki is foremost a tool for writing and collaborating on documentation, and only secondarily a site for reading it.

The Wiki project aims to promote 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 was put in place as an efficient solution for both Gentoo users and developers to work together on up to date documentation, allowing fast paced progression, while aiming for the highest standard.

Developers, of course, 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 lets the community take an active role in maintaining documentation, allowing developers, documentation writers, users, and even just casual readers of the wiki to collaborate. Corrections, additions, and discussions about documentation all take place through the wiki.

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 fora through which to participate, such as the Gentoo IRC channels, forums, mailing lists, https://bugs.gentoo.org - 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, or 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!

The number one rule of wiki editing, is to be bold - other wiki contributors can correct mistakes later, so have confidence. Dive in and make changes - as long as pertinent additions are made, layout issues can be fixed by more experienced editors later.

Tip
Keep in mind that more experienced editors and administrators will often rework additions - this is not a criticism, simply part of the process. Sometimes edits will be reverted, if they are too far off usual practices - this doesn't necessarily mean that there is no value to a change. Start by making small edits to pages, to get a feel of how things are done.

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 understandable, but there will usually be good reason. There are 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.

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.

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, 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 a preview, to 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.

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.

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, for reference. 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!

For anyone willing to contribute a bit more, 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, for subjects of particular interest, 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. Resolving a problem after asking for support, it is particularly useful to contribute solutions back to the wiki, so that people providing support might avoid future requests for the same issue.

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.

Closing open discussions by replying to questions or implementing changes is particularly helpful, and will keep things more focused.

Keep an eye out for 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.

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

Sometimes, when trying to save changes to an article, an error that starts with "Error: This action has been automatically identified as harmful, and therefore disallowed" and finishes by mentioning an abuse rule: "Disable writing internal wiki links as external besides required". This error is shown in a large red box when trying to save an article, and will prevent any changes from being committed.

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.