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

  • 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.