This page explains the considerations that should be taken when writing pages in the HCoop wiki.
Template
Here's a basic template to apply when making new pages and revising old ones.
Description of page. I.e.: This page describes how to filter your email using procmail and Exim. ## Every page should have a table of contents [[TableOfContents]] Remaining content of page, split into logical sections.
Section numbers
The following text, when placed at the beginning of a page, turns off numbering of headings.
#pragma section-numbers off
This should be used:
- If the page is the main page, or exactly one degree away from it, then you should include the following text at the very top of the page.
On multi-page guides, such as DomTool.
- On other pages at the discretion of those who keep the wiki up-to-date.
Level of headings
If section numbers are turned off, then start with first-level headings.
If section numbers are left on, then start with second-level headings. The reason for this is that the numbers in front of first-level headings look ugly and distract from the content of the page.
Why not hack on the style instead? --AdamChlipala
Writing commands
If you are writing a command, then put it on a separate line, so that it stands out and is easy to copy and paste.
Bad: my-command foo bar.
Good:
my-command foo bar
Writing style
It would be best to use "you" (second-person) when writing the MemberManual.
For other pages, it probably doesn't matter.