Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Info

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

On this page:

Table 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:
    Code Block
    none
    none
    *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: *In this section:* {children}
    Code Block
    none
    none
    
    {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.