Gentoo Wiki:Contributor's guide - Gentoo wiki

Gentoo Wiki:Contributor's guide - Gentoo wiki
Jump to:
content
Gentoo Wiki:Contributor's guide
From Gentoo Wiki
Jump to:navigation
Jump to:search
Wiki Help pages
Contributor's guide
Fixing errors
Guidelines
Blueprints
Wiki FAQ
About Gentoo wiki
Wiki project page
Talk pages
Contributing to Gentoo
Code of conduct
Help improve the documentation!
Editing pages
Formatting
Translating articles
Links
Images
Categories
Templates
Moving (renaming) a page
Redirects
Deleting a page
Starting a new page
more
Spot a mistake, omission, broken link, etc.? Please
just fix it
, it's easy!
Making a small change is simple:
once logged-in
, click the
Edit
button at the top of a page or next to a section title, make the appropriate change to the text, add a brief summary stating
what
the edit changes and
why
, click the
Save changes
button - done!
For useful information on editing the wiki, see the quick-start guide on
what to do when noticing an error on the wiki‎
, the
contributor's guide
, and the
guidelines
For the
occasional quick fix
, don't necessarily worry too much about
formatting and style
if it's too much - what's important is to fix errors or add missing information to the wiki.
If having any trouble getting started, there are often people willing to help in the
#gentoo-wiki
webchat
IRC
channel. Please be patient, replies can take a very long time: be prepared to wait for several hours after asking a question.
Note that some articles are protected from public edits, such as the
handbook
and
project pages
. Issues on these pages can still be
reported
though.
For anyone willing to help the Gentoo community out a little more than with the occasional quick fix, please do check out the
contributor's guide
and the
wiki editing guidelines
to learn how to make quality edits. The
help improve Gentoo by getting involved with documentation!
page lists many of the ways wiki content can be improved.
See also
For anyone looking to help
translate
the documentation, see
translating wiki articles
. For other ways to contribute to the Gentoo project beyond the documentation wiki, 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.
Adding-to and improving this 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
This guide will help anyone quickly get started with simple edits, to begin improving articles in minutes!
It is complimentary to the
guidelines article
which explains how to make quality edits that are consistent across the wiki, while the
help improve Gentoo by getting involved with documentation!
page details how to discover areas for contribution, and the
help pages
provide comprehensive documentation on how to edit wiki pages.
The majority of the documentation on the wiki is publicly editable, and is written by basically anyone willing and able to volunteer useful contributions. Whether it's the occasional small addition - or fuller contributions from people willing to learn a little about the art of editing documentation on the wiki - corrections, constructive additions, and useful changes benefit the
free software
free software
community at large!
Please, read on, and happy editing!
Important
All contributions
must
comply with the
Gentoo wiki copyright policy
and with the
Gentoo AI policy
. You must
be sure to understand and accept those policies
prior any contribution.
The
wiki project
aims to maintain a respectful, constructive environment - please be polite and considerate of other users, and be sure to follow the
Gentoo code of conduct
. 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
See also
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.
See also
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.
Contents
Getting started
General editing advice
Wiki markup primer
3.1
Headings
3.2
Text formatting
3.3
Links
Writing good articles
Areas for contribution
See also
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.
Note
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.
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 - 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.
Tip
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).
Note
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
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).
Tip
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.
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 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.
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
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
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|}}
Use the
{{Path}}
template to indicate a path, or filename:
{{Path|}}
Start lines with an asterisk
to create a "bullet list".
See also
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|}}
To have a label that is different to the page name, the second argument can be adjusted:
{{Link||}}
To make an external link, the address can simply be surrounded in single square brackets:
[https://example.com/...]
Important
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/... ]
Note
The "double square bracket"
[[Link]]
syntax should be avoided, as it does not work well with the translation extension.
See also
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 to ". 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.
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
See also
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
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 the writers and editors who collaborate to create useful, quality documentation
What to do when noticing an error on the wiki
what to do when noticing an error on the wiki
, to get things fixed
Retrieved from "
Category
Gentoo Wiki