Protocols

Using Headings

Generally the page title is the first-order heading, and the main page subtitles begin with Heading 2. Further subheadings are used as needed. Logical headings are important for scanning a page as well as for a helpful Table of Contents. Headings are set in the existing template.

If the headings go really deep (say, to fourth and fifth levels), then consider starting with level one instead of level two.

Think about the structure/presentation of your topic and how it will look in a Table of Contents – which you should use if your page requires much scrolling. Tables of Contents, where topical headings and subheadings are well thought out, help viewers quickly find what they need right at the top of the page.

Placing Pages

First, use the Search function to ensure that someone hasn't already added a similar page.

If not, think about where your page should go within the established hierarchy (see Tree Categories, above).

When to Add a Table of Contents

Required if your page requires much scrolling, like this one!

  1. Place cursor at top of page ABOVE the first heading in the body.
  2. Click Insert > Table of Contents
    1. If it makes sense as shown in the macro viewer, set any parameters and click "Insert"
    2. (If it doesn't quite work, click "Cancel," rework your heading formatting, and try again.)
  3. The TOC macro tag will show in the editor. 
  4. Click "Save" when done.

When to Add a Change History

You can view the change history of any document by going to its page and clicking Tools > Page History. However, if the document is being created by more than one person, requires approval, or might be audited, it might be best to add a Change History macro below the Table of Contents: 

  1. In the editor of the target page, place the cursor beneath the Table of Contents macro tag.
  2. Click Insert > Other Macros > Confluence Content
  3. Choose "Change History"
  4. On the macro preview, set any parameters and click "Insert" 
  5. The "Change History" macro will show in the editor. 
  6. Click "Save." 

Use Code Boxes

Please use for all code documentation. Be precise with the spacing: please use 4-space increments to indent a line of code. 

  1. In the editor, highlight the complete section of code
  2. Click Insert > Other Macros > Formatting
  3. Choose "Code Block"
  4. Select any parameters on the right. For example, in each code block, on the right in the preview pane, you can choose syntax highlighting, among other things, to format it.
  5. Click "Insert."
In the editor, delete any spaces such that the code block immediately follows the text describing it. Once you save, a little more space will be added. Otherwise you get large gaps on the page. You can use "Preview" button at the lower right of the editor to check out the final appearance before deciding and saving.
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
 
public class MyClass {
    // The "static" isn't required but is a nice memory saver expecially
    // when you expect several instances of this class. If the class is a
    // singleton, it is OK to drop the "static" keyword.
    private static final Log LOG = LogFactory.getLog(MyClass.class);
}

Use Callout Boxes for Important Notes

These pull out text that is especially important to make it stand out rather than be lost in a sea of characters. Find them under Insert > Other Macros > Formatting, then scroll to the appropriate option (these four have icons, but there are other options for setting off text). For example:

This callout is good for extra information, say, about the version or history of an app or document and where to go for supplemental information, that you want to stand out from the rest of the text.

This can be, for example, a helpful tip.
In the help documents, we are using this callout for "Note:" statements, as for a cautionary or other important note—an extra detail, something to pay attention to—but is short of a warning.

This is a warning! (like, Achtung! Verboten! Don't do this! Caveat Emptor! 'S death!)

Common Actions

The "Insert" button on the editing toolbar is your source for all kinds of items and macros, from emoticons to a table of contents to any of a plethora of handy macros. For macros, a few common ones are on the dropdown menus, and many more are under the "Other Macros" option, which itself has sets of macros for different types of needs. Several especially useful ones are described below.

Adding Attachments

Multiple attachments

Attachments, especially if you want to provide several, will stand out best (and are easily managed) using the Attachment macro, usually at the top or bottom of a given page. To insert this macro:

  1. In the editor, click Insert > Other Macros > Confluence Content
  2. Choose the Attachments macro at the top, set any parameters, then click "Insert"
  3. The Attachment macro tag will appear on the edit page. 
  4. Click "Save" when done. 

Looks like this (notice that the attachments embedded throughout this page are displayed here):

 

 PNG File image2013-3-4 16:3:9.png4 kBJuliette WilsonMar 04, 2013   
 PNG File image2013-3-4 16:2:31.png4 kBJuliette WilsonMar 04, 2013   
 PDF File FWS_map_template_specs.pdf192 kBJuliette WilsonJan 25, 2013   
 Microsoft Word Document Confluence_UsingTheEditor.docx86 kBJuliette WilsonJan 25, 2013   
 PDF File TransferInventory[1].pdf164 kBJuliette WilsonJan 25, 2013   
 
Creator
Labels
Comment
 
 

 

You or anyone can now attach documents directly on the page using the macro. 

Embedded attachments

If you just want to add just one attachment, or embed attachments in-text:

  1. In the editor, place your cursor where you want to insert the file.
  2. Click Insert > Attachment
  3. Choose a file to upload.
  4. Change the "Link Text" if desired (default is the filename, used in this example).
  5. Click "Insert" 
  6. A link to the file will appear on the page, e.g.: Confluence_UsingTheEditor.docx

Note: If there also is an Attachment macro on the page, each embedded attachment will automatically be uploaded to it.

Adding Links

Links work much like individual attachments:

  1. In the editor, place your cursor where you want to insert the link.
  2. Click the "Link" button on the editor toolbar.
  3. Choose the type of link (from Search, Recently Viewed, Attachments, Web  Link, or Advanced [insert a link into the page]).
  4. Follow instructions to find and upload the link.
  5. Change the "Link Text" if desired (default is the URL or filename).
  6. Click "Insert" 
  7. The link appears on the page (gave this example a name), e.g.:  Confluence Help Page