Welcome to the IPFire Wiki

This wiki is a community-maintained resource about everything there is to know about IPFire. Join us and help us improving it!

Looking for something?

Use the search and find answers to everything about IPFire. If you cannot find what you are looking for, join our community and talk to fellow IPFire users, developers and everybody else involved in the project.

IPFire Community

Differences in Revisions: basic_documentation_guidelines

old an unreferenced
# Basic Guidelines for Documentation
 
## Guidelines
 
* Be sure to use the fully qualified namespace in any article you create
* Every article should have a H1 as the first line in the article with the human friendly name of the article.
* Beginning in column 1, put six equals signs *=*), a space, the title of the article, a space, then six more equals signs.
* Remember, the title will be displayed in the main menu on the left, so it should be as concise as possible.
* If the article is more than a few lines long, break it up into sections using H2, H3, or even lower headings. These are just like the H1 above, just with fewer equals signs (five for an H2, four for an H3). This allows Dokuwiki to build a nice menu in the article itself.
* Long articles make it difficult to find the information you need rapidly. If your article is over one or two screens, consider if you can break it into two separate articles.
* Articles should be in English if at all possible. If you are unsure if you are communicating well in English, write the article, then ask for a review on the documentation mailing list.
*
 
## Namespaces
 
Dokuwiki is divided into **namespaces**. Think of a namespace as a category for the article you are writing/editing. The IPFire wiki uses these namespaces to allow readers to rapidly find the information they need.
 
When viewing or editing an article, the namespace and the article name can be seen in the upper right hand tab on the article. For example, this article is*Basic Documentation Guidelines* in the namespace*Docs*, which is in the namespace*Projects* so in the upper right corner, you will see
 
` projects:docs:basic_documentation_guidelines`
 
**Note:** article and namespace names are converted to lower case, and spaces are replaced with underscores.
 
### Namespaces can contain Namespaces
 
Namespaces can contain namespaces, again separated by a colon. While it makes no sense to do that for the Documenters namespace, having something like confguration:firewall allows the number of articles displayed in the menu kept down to a manageable number, and allows the user to find information by drilling down.
 
### The "Default" Page for a Namespace
 
There is a special article you can write for a namespace, named **start**. Creating an article inside a namespace named start defines the default article for that namespace. For example, Configuration:start would display when anyone clicked the Configuration menu option, and Configuration:Firewall:start would do the same for the Firewall namespace under the Configuration namespace.
 
There should always be a **start** page for any namespaces defined. The first header in the start page (generally, an H1 defined by six leading and trailing equals signs) will be the display name for the namespace.
 
### Number of Namespaces
 
While namespaces can be very powerful, you want them when you are going to create several articles that can be logically grouped together. Creating a new namespace to hold one article defeats the purpose of using namespaces in the first place (unless there is a need for more articles in the future).
 
Before you create a new namespace, stop and think. Can a different namespace be renamed to include this article? Is there another way to do this? Then, if you decide to create a new namespace, do it.
 
### Menus and Namespaces
 
The namespace hierarchy is used to automatically determine the layout of the menu displayed on the left of the screen. The menu will display the namespace in the tree defined by the namespaces.
 
## Menus
 
There are two menus to be concerned with in the documentation. Both are dynamic, automatically changed when an article (or namespace) is added, edited or deleted.
 
The menu on the left shows the namespaces, along with the article names, for all articles in the wiki*unless the namespace has been specifically excluded from the menu*. This is the menu the visitor uses to find the correct article.
 
When you are viewing an article, **if** you have multiple levels of header tags (h1, h2, h3), they will form a menu in the upper right of the article itself, making for easy navigation within some longer articles. For example, [](projects/docs/Quick Syntax Overview) has a horribly long menu on the left side because it has a lot of categorized information and was specifically written to display that functionality.
 
Because of this, check your namespace before creating a document. And, when you write an article, consider using nested layers of H1-H5 headers inside it if it is more than a few lines long.