Everyone is welcome as an editor on this wiki. It needs you. Every individual brings their own element to every page and helps to make it more accessible, more information or simply: better. But to not have too many different styles of writing, we have collaboratively written these guidelines:
Keep things short & easy
People from many different backgrounds are Using IPFire and reading these pages. Not everyone - in fact the majority - does not speak English as a first language. Therefore it is important to keep the language as simple as possible so that everyone can understand. Sarcasm or other implicit ways to say things have no place in technical documentations. Use an active voice to keep sentences clearer.
Pages and sentences should be short and to the point. It is very easy to write too much than too little. The goal is to find information quickly and that needs structure. Pages should be easy to find and cover one thing.
Write a short introduction on top of the page what to find. This should normally not be longer than a sentence or two. An outro can tell people what they should have taken away from a page or what it did not cover. In rare cases, you can give some further reading.
Do not try to be exciting. Technical documentation might be boring, but it has to be very clear.
Although what you are writing is probably important, there is not need to a big box around it. If users need to be made aware about something, put it in a position everyone will see. “Note” and “important” do not need to be set in bold next to them.
Headlines
Headlines should be short and universal. They should not refer to the upper section. For example:
Advanced IPsec Configuration # BAD
Advanced Configuration # GOOD because the should be in the IPsec section
All headlines should be capitalised:
Advanced Configuration # Correct
Advanced configuration # Incorrect
They should also use gerunds:
Adding Users # Correct
Add Users # Incorrect
Navigations
Do not build your own navigation. People should follow a clear path to a certain page. If they need to go one level back up, their browser already has a Back button. Since plenty of people read this on mobile, they would probably execute a gesture to go back.
Do not use tables for navigations. Bullet lists should be fine instead. Tables have a bad flow and a hard to build for various screen sizes.
Sections
Make the page easily scannable. Subsections and headers help to find the right section to read.
Avoid a wall of text and use lists and tables to present data.
Use the structure to mark important information. That goes to the top. Do not use bold font to mark important things.
Code
Use code and code blocks to explain actions.
Include an example output of commands on the shell when possible.
Images
Images should be used to illustrate things. They should not be used too much when one or two sentences are enough to describe what the image is showing.
You have to be the author of every file being uploaded, hold the copyright or have permission from the original copyright holder.
Do not downscale images, because the wiki will automatically take care of this and deliver an appropriately downsized version for each device. However, images should not be uploaded in an absurd resolution to not waste too much space on our servers.
There are different categories of pictures:
Screenshots
Use a good resolution and do not capture any surroundings that are irrelevant to what you are trying to show.
Use example data instead of editing the picture and blurring information wherever you can.
Diagrams
If you draw any diagrams, please always upload the source file, too, so that others can edit it.
Photos
If you take any photos, use a good camera with a high resolution.
Do not use any images for other purposes like icons, etc. The wiki will take care of this wherever needed. Under no circumstances link any external images.
Styles of Writing
People have different styles of writing. Some use American English, others use British English. Both are fine.
If you edit an existing page, follow that style and use the spelling of the original author (e.g. neighbour instead of neighbor or vice-versa). The same goes for Oxford comma, etc.
Always use auto-correct and double-check your spelling before you submit your edits.
Remove any words that do not add anything or give a connotation about that things are "easy". For example: Simply, Clearly, Just, Of course, Everyone knows, Easy, However, So, Basically, Turns out, In order to, Very
Internal Links
You should use the headline feature of the wiki and avoid replicating them:
[My Title](./another-page) # BAD
[](./another-page) # GOOD
The wiki will automatically grab the headline from the linked page. This helps to keep titles consistent in navigation and makes the right page easier recognisable. It also saves you from typing.
External Links
Everyone is encouraged to link to other pages. Those should be well-known and stable (i.e. should not vanish from the Internet after a couple of days).
Links to Wikipedia (the English one of course) should be added to give some background, but should not be used to explain obvious things that can be assumed to be well-known (e.g. IP addresses).
Content from the Community Portal should be edited and copied into the wiki and not linked. Known issues and long-standing bugs can be linked to Bugzilla for more information.
Do not stop yourself from writing
The first draft does not have to be perfect. Write something and have it read by somebody else who can help you improve it. You must come back to finish your page very soon after starting it.