1. WMS Contributor Agreement
Please refer to the information and agreement on the WCA-01.
2. Deleting, moving or renaming pages
Do not delete any page. Move to Recycle Bin instead!!!
- External sources may refer to the page. For example, the Confluence application itself contains hard-coded links to certain pages in the documentation, especially the online help, README file, or setup wizard. Other applications also have links to the documentation pages.
- Page names are included in some Confluence macros, such as the {children} macro and the {include} and {excerpt-include} macros. If you rename, move or delete a page, you may break other pages that contain such macros.
3. Adding a hyperlink that points to another page
Please use relative (internal link) rather than absolute (the full http://xxxx external link) format when linking to another wiki page. This applies to pages in the same space or in another space. Refer to Working with Links for details.
- Broken links: You will see immediately if the link is broken. Confluence will colour the link red if the page does not exist.
- Automatic update of page name: If someone changes a page name, Confluence will automatically update all internal links.
- Space exports: We export documentation to PDF, HTML and XML format, for use by many customers who cannot escape their firewall to access our online documentation. They download the exported files and install the documentation on their own systems. The external links in such offline documentation will link back to the online wiki, instead of linking to the correct page in the downloaded documentation, causing much irritation to the customers.
- Release management: Hard-coded links break the release management system we have in place, where documentation for previous versions of each product is held in separate archived spaces.
4. Updating content that is re-used in other pages
Be aware that the content of some pages is re-used in other pages. We use the {include} and {excerpt-include} macros to dynamically copy content from one page into another page, at the time of rendering the page.
Inclusions Libraries
A specific example of content re-use is the pages in our 'Inclusions Libraries', such as the User Management inclusions library. Take a look at the page about nested groups. The entire content of this page is included into a page in the Confluence documentation (here) and also in the JIRA documentation (here).
5. Maintain a consistent style
When you add or update content, please use the same layout, grammar and formatting as the rest of the page or space.
At Atlassian, we pride ourselves on the quality of the documentation. We see it as part of the product. Consistency and correctness of syntax, spelling, punctuation and style contribute significantly to the quality.
For more details, see the Writing style guidelines.
6. Mark your drafts as "Work in progress"
When writing a lengthy piece of documentation, you may need to save the page before you have finished it. Please mark all such drafts or unfinished work, with an information box at the top of the page.
7. Documentation Style Guidelines
The easiest way to understand how to style your writing is to read our Writing style guidelines and look at existing pages in our documentation. However, if you have specific questions about style, we have included more detailed guidelines below:
General Page Structure 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 coloured 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.
Typographical Conventions Guidelines
- Heading hierarchy: Start with H2 and go down in sequence. If your page is short, there is no need for a heading.
- Capitalisation: For existing products, in headings and page names, use sentence case (Capitalising only the first letter) rather than title case (Capitalising All the Big Words). In other text, capitalise 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 colourful 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 colours, 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 UK English.
Task Description Guidelines
- 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:
- Select Admin > Repository List > Add repository.
- Select a Repository type from the dropdown list.
- 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.
Screenshot Guidelines
- 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 italicised 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).
