Author Guidelines

• Page name: Most pages should start with a gerund (e.g. "Adding a user").
  
• Introduction: Write an introduction that provides useful context, i.e. why a reader would use the function, not just what it is.
• Content: Limit page content to one major topic per page, where possible.
• Table of contents: Use a table of contents, if there is more than one header (other than Notes) on the page. Include h2 to h4 only. Position the table in the top right of the page in a panel titled 'On this page'.
• Pre-requisites: List pre-requisites in a 'Before you begin' bulleted list before the procedure. If the pre-requisites apply to more than one procedure on the page, create a new section for it after the introduction.
• Procedure: Describe the procedure in numbered steps in a new section.
  
• Screenshots/Diagrams: Display screenshots/diagrams after the text that it is related to.
• Next Steps: If the page leads logically to another page, include a 'Next Steps' section containing the appropriate link(s).
• Notes: If a note does not need to be displayed next to a particular step/point, list it in a 'Notes' section at the end of the page. If you need to warn a customer about a critical issue, add it after the introduction. Avoid using too many colored panels.
• Related pages: Add links to relevant related pages in a 'Related Topics' in a panel next to the opening paragraph. Use Confluence page layouts or section/column macros to layout the content.
• Labels: Add labels. Search for existing labels before creating new ones.

Example:   Defining Plan Variables

• Heading hierarchy: Start with H2 and go down in sequence. If your page is short, there is no need for a heading.
• Capitalization: For existing products, in headings and page names, use sentence case  (Capitalizing only the first letter) rather than title case (Capitalizing All the Big Words). In other text, capitalize only the first letter of proper nouns. Use lower case for the names of features or concepts used in the application, such as screen and issue (Jira), page and comment (Confluence), plan (Bamboo), etc.
• Quotation marks: Use single quotes rather than double.
• Emboldening: Use bold text selectively, because bold text is used in UI elements.
• Referring to UI elements: Use bold text.
• Emphasis: Use italics only.
• Warnings, notes and other boxes: Avoid colorful boxes. People don't read them.
• Code snippets: Use the code macro for block-level snippets. Use monospace formatting for inline snippets.
• General style: Do not override the colors, fonts and text styles provided by the Documentation Theme (or whatever theme your space is using.)
• Lists: Use numbered lists for instructions, and only for instructions. Use bulleted lists for other lists. Do not use a list if there is only one item in it.
• Spelling: Use US English.

When in doubt, consult our style reference guide:  the Style manual for authors, editors and printers, sixth edition, published by John Wiley & Sons Australia, Ltd.

Example:  Managing Nested Groups

• Some pages might encompass multiple sub-tasks that make up a larger task. If so, use numbered headings for each sub-task.
• Use numbered steps (i.e. a numbered list) for each task (or sub-task).
• Use '>' to keep instructions as brief as possible.
• Omit the obvious (e.g. "Click the OK button").
• Where possible, reference instructions and/or screenshots on the same page (though not on other pages), rather than reproduce the same steps multiple times. E.g. "Go to the 'Custom Fields' screen as described [above]"
• Document complex, important or non-obvious fields in detail. Consider omitting documentation for obvious fields, especially optional ones (such as the Description field on many admin screens in Jira).
• Only describe input for specific fields on the screen where needed. If you need to describe multiple fields and cannot get the text added to the UI, describe it in the procedure using a table (> 3 items) or bulleted list (< 3 items)
• If you need to document lots of complex, important or non-obvious fields, use a table.

Example:

To add a repository:

1. Select Admin >  Repository List > Add repository.
2. Select a Repository type from the dropdown list.
3. Specific fields will appear on the 'Add Repository' screen, depending on the chosen repository type. Enter the repository details as prompted. You will find more information in the specific sections listed below.

• Usage: Only use screenshots when you really need them as a "location anchor" for users, but not for every point in a series of steps.
• Format: Save screenshots in PNG format.
• Screenshot size: Capture screenshots and present them on the page at their full-size. However, if they are bigger than 700px wide, reduce their size in Confluence to 700px.
  • Avoid altering their size in an image editor — let Confluence do the shrinking (if it's required), since when viewing the page, you can always click the image to view its full size.
  • For Gallery Macro: To be determined by Analytics stats on usage of printed versions.
• Border: Add a Confluence border around each screenshot.
• Edge effects: Use the Snagit fading effect when available.
• Anti-aliasing: Ensure that any area of screenshot you are capturing is anti-aliased. On Windows operating systems, this usually entails ensuring that ClearType has been activated in your Display Settings.
• Only include necessary detail: When taking screenshots, omit any unnecessary detail. Only include the area of the page (or menu items) applicable to the context described in your documentation.
• Captions: Place captions above screenshots in italicized text. Unless a screenshot description is absolutely necessary, do not use captions on screenshots incorporated into procedural steps.
• Indenting screenshots: Screenshots should not be indented (i.e. appear flush against the left of a page) unless they are part of procedural steps, in which case, use Confluence's Ctrl+Enter feature to ensure they are indented to the correct step level.
• Annotations: Use Gliffy. Don't use Snagit effects (except edge fading).