#pragma section-numbers off

This page explains the considerations that should be taken when writing pages in the HCoop wiki.

[[TableOfContents]]

= 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
    Because the size of the normal unnumbered headings look about right.  Perhaps we should just turn section numbering off globally.  I could do that easily.  --MichaelOlson

= Depth of headings =

For the MemberManual, there should be no more than two levels of headings, so that the distinction beween different levels may be clearly seen.

= 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
}}}

= Point of view =

It would be best to use "you" (second-person) when writing the MemberManual.

For other pages, it probably doesn't matter.