Child pages
  • Documentation Style Guide
Skip to end of metadata
Go to start of metadata

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

The first version that actually follows these guidelines is the Fedora 3.5 Documentation. Older documentation is not expected to conform.

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