Wiki Style Guide

This is a style guide to help us make the form of pages on the wiki more consistent.

Contents

  1. General form
  2. Content considerations
    1. Referring to commands
    2. Describing changeset graphs and other diagrams
    3. Discussion
  3. Mercurial naming conventions
  4. Page naming and linking conventions
    1. Renaming pages
  5. Section headings
  6. Useful categories

1. General form

Pages should have the following general form: 

= Page Title =

A brief overview.

<<TableOfContents>>

== Section 1 ==

Section 1 text.

== Section 2 ==

Section 2 text.

----
CategoryA CategoryB

Pages with only a couple paragraphs of text may collapse this to: 

= Page Title =

Full text.

----
CategoryA CategoryStub

Please be sure pages are added to appropriate categories.

2. Content considerations

The wiki is intended as a primary source of documentation, not as an informal discussion. Thus, wiki pages should aim to use a formal third-person style.

2.1. Referring to commands

Commands should generally be described as a sequence of operations and their typical output in a preformatted block: 

$ hg init
$ hg add foo
foo: No such file or directory

When referring to commands inline (eg 'hg revert -a'), use quoted monospace: 

'`hg revert -a`'

2.2. Describing changeset graphs and other diagrams

The Mercurial wiki has a built-in facility for drawing arbitrary graphs:

2.3. Discussion

Questions or discussion about content should be moved to a subpage named Talk, eg WikiStyleGuide/Talk, though generally such discussion is even better directed to the mailing lists or IRC.

3. Mercurial naming conventions

4. Page naming and linking conventions

Page names should all conform to WikiCamelCase so that editors and users don't need to remember the non-semantic content of page names. Some corner cases:

Page titles, in contrast, should be 'book title capitalized':

To link to a page, you should generally use appropriate lowercase as the anchor text: 

  [[InformationForDevelepers|information for developers]]

4.1. Renaming pages

When renaming an existing page to comply with the naming convention, please add a redirect from the old page to the new one of the form: 

#REDIRECT NewPageName

5. Section headings

6. Useful categories

CategoryWiki