The following guidelines should be followed within the Official Fedora Documentation.

On this page:

Headings

• Use h1. for top-level headings (major sections).
• Use h2. for subheadings, then h3., and so on.

Callouts

• Use {tip} for tips that suggest a beneficial, but optional action.
• Use {info} for other helpful information.
• Use {note} for warnings of medium importance. If these are not followed, it is possible that the user will experience moderate problems.
• Use {warning} for warnings of high importance. If these are not followed, there it is possible that the user will experience severe problems.

Introductory Text

• Don't have an "Overview" or "Introduction" section. Instead, just start the page with introductory text.
• If a table of contents is present, it should immediately follow the introductory text.

Tables of Contents

• If a page exceeds two sections, it should have a table of contents allowing readers to quickly understand the major sections and jump around, if needed.

• The wiki markup for a page's table of contents should look exactly like this:

  *On this page:* {toc}

• If a page is simply a container for other pages (e.g. a "section" of documentation), the body's wiki markup should be exactly this:

  {panel} {children:style=h3} {panel}

Page Titles and Section Headings

• Use Heading Case, Where Most Words Are Capitalized
• Do not use hard-coded numbers in headings or page titles.

Fixed Width Text (inline)

• Use {{two brackets}} around text that should be monospaced inline.

Fixed Width Text (blocks)

• For code examples, use the {code} macro with no modifiers, only specifying the format if absolutely necessary; Confluence is good at guessing the format for syntax highlighting purposes without you having to be explicit about it.
• For other blocks of fixed width text, such as text that users are expected to enter at a prompt, use the {noformat} macro with no modifiers.
• When using either the code or noformat macros, put the start and end tag on a line by itself to enhance readability.

Hyperlinks

• Use wiki links whenever possible – these are much easier to maintain.

FAQs

• One question per page
• Unlike other pages in the wiki, the title should be a question and need not use Heading Case.
• Questions use the pronoun "I", not "You".
• Questions use the phrase "How do I" in preference to "How can I"

Things to Avoid

• Inclusions - these are problematic when copying Confluence spaces around.
• Page Labels - they provide questionable value and are not maintained.
• Anchors - only use these where absolutely necessary. They are difficult to maintain, and often end up getting deleted or forgotten.