Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Version History

Version 1 Current »

This page contains important information for anyone updating the WMS documentation wiki.

In brief:

  1. Please read the WMS Contributor Agreement.
  2. Do not delete, move or rename any page unless you created the page yourself.
  3. Use internal link format rather than the full http://xxxx external link format.
  4. Be aware that the content of some pages is re-used in other pages. Make sure you put your content in the right place.
  5. Make sure that you update the relevant version of the documentation. We maintain a separate set of documentation for each major version of most applications, as specified in each documentation space name.
  6. Maintain a consistent style, layout, grammar and format as the rest of the page or space.
  7. Mark all drafts clearly as work in progress.
  8. Please do not edit the release notes, security advisories or policy documents.
  9. Please read these detailed style guidelines.

On this page: 

   

1. WMS Contributor Agreement

Please refer to the information and agreement on the [WCA-01]

 

2. Deleting, moving or renaming pages

 

Your own pages only

 

Please do not delete, move or rename any page unless you created the page yourself. Then consider carefully before you delete, move or rename your own pages.

 

In many of the documentation spaces, only Administrator (or self page) will have permission to delete a page, comment or attachment. If you need something deleted, please raise a request in the appropriate project on our JIRA issue tracker. For example, if you are requesting a change in the Confluence documentation, raise a request:

  • in the WMSSD project
  • with issue type = 'Task'
  • and component = 'Documentation'.

Deleting, moving or renaming a page can be perilous, because:

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

Good (tick)

Bad (error)

My Page Name
OTHERSPACE:My Page Name
Why is internal link format best?
  • 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).

 

If you want your information to be included in all relevant spaces, put it into the page in the Inclusions Library. If your content is relevant only to one particular space (e.g. Confluence only or Crowd only) then add it to the page in that space.

 

5. Document the applicable version of the application

Most of our documentation is version-specific. In general, we maintain a separate set of documentation for each major version of each application. When adding or updating documentation, please check the space name and make sure that your update applies to the version specified in the space name.

 

For each product, there is a current documentation space plus potentially one or more archive documentation spaces holding documentation for earlier versions of the product. For example, the current Crowd documentation is in the /wiki/spaces/~jessie/pages/22151385  space, and documentation for earlier versions is in WMS-01, WMS-02, etc. Editing of the archive spaces is restricted to Atlassian technical writers. To request an update to such a document, please raise an issue on our JIRA issue tracker, in the project for the relevant product. Set the issue type to 'Task' and the component to 'Documentation'. In isolated cases, we may grant someone edit-permissions for a specific update and then remove the permissions again.

 

 

6. 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.

 

7. 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.

Example:

Work in Progress

 

This page is a draft. Treat it with caution.

 

8. Don't Edit Release Notes, Security Advisories and Policy Documents

Please do not edit the following types of documents:

If you feel that something needs changing on a page which falls into one of the above categories, please add a comment to the page rather than editing it. A technical writer will respond to the comment. We are watching the documentation spaces, and will pick up any edits and/or comments as soon as we can.

 

9. 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.

Example: Defining Plan Variables

 

 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 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

 

 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:

  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.

 

 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).

Related articles

 

 

 

  • No labels

Private & Confidential