Protocols and Editing Tips
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.
Think about where your page should go within the established hierarchy. In this ECOS Help wiki, each application has a parent page, and everything else is either content on the parent page or a child page of it.
- Organize it logically, and if it's a user manual or guide call it that, with the app abbreviation as the first word in the title (of at least the parent page): e.g., "HabITS User Guide." In TAILS, for example, the Bull Trout Effects Take instructions (formerly COED and still a stand-alone user guide) occur as a subset of Chapter 9, but the Bull Trout Effects-Take manual has its own chapters. So all of the TAILS chapters are identified as "TAILS Chapter X. Title" and the Bull Trout Effects-Take Chapters are identified as "BT Effects-Take Chapter XI. Title." This keep people clear if they randomly land on a Chapter page: they immediately know which app they're in.
When to Add a Table of Contents
Required if your page has at least three headings and requires much scrolling, like this one! (So almost always.)
- In Edit mode, place cursor at top of page ABOVE the first heading in the body.
- Click Insert > Table of Contents
- If it makes sense as shown in the macro previewer, set any parameters and click "Insert."
- If it doesn't quite work, click "Cancel," rework your heading formatting, and try again.
- The TOC macro tag will show in the editor.
- 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:
- In the editor of the target page, place the cursor beneath the Table of Contents macro tag.
- Click Insert > Other Macros > Confluence Content
- Choose "Change History"
- On the macro preview, set any parameters and click "Insert"
- The "Change History" macro will show in the editor.
- Click "Save."
Use Callout Boxes for Important Notes
These pull out and frame 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 (the four that follow have icons, but there are other options for setting off text). For example:
NEED MORE INFO?
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.
NOTE (or, IMPORTANT NOTE)
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.
By the way, use the "Optional title" field in the previewer to type in the text you want to show, like "NEED MORE INFO?" or "GETTING HELP" or "IMPORTANT NOTE" or whatever. I use caps because they stand out more, but whatever you do be consistent. On the one hand, consistency in the many "IMPORTANT NOTE"s in TAILS are easy to eyeball as something to look for; while in other places, you might want to vary the title text to draw the eye to unique sorts of notes and hint at the nature or importance of certain callout content, like "NEED MORE INFO?" vs. the generic "NOTE."
This can be, for example, a helpful tip.
This is a warning! (like, Achtung! Verboten! Don't do this! Caveat Emptor! 'S death!)
A NOTE ABOUT NOTES
In the editor, delete any spaces such that the callout box 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. (And sometimes, the spacing gets weird with Notes and tables, and won't stay saved once you open the editor again; haven't figured out how to make it behave.)HabITS Accomplishment Type Definitions
I've used this macro to frame an exampole document on a help page or otherwise contain something unique, like a set of a couple examples. You can also add a title, select background color and font color for the title bar, select a border color, and a background color for the text box. See examples at Creating a Custom Letter for your IPaC Species Lists (letter content is within a panel) and HabITS Accomplishment Type Definitions (this uses tables to line out the Examples, and the advantage here is table width conforms to text length; but you could do this):
Evaluations of management actions
Monitoring of changes over time
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.
Images can be plucked from Word (copy/paste) or captured and then copied/pasted from those made with SnagIt or similar. There are a couple things you can do once it's in Confluence (add a black border, resize), but if you are using added-on circles and arrows on figures, do those in the capture software and then grab the whole image and place it in Confluence. (For any screenshots I added, I applied a medium blue border (and any circles, boxes, or arrows around particular parts of the image) in SnagIt to all newly captured images—stands out better and looks nicer—before pasting it onto the Confluence page.)
To resize, add a border, link to other content, or apply an interesting "effect," click on the image and then, in the tool bar that appears above or below it (depending on where your view is):
- Click on the pixel box and change the number to more or fewer, depending on whether you are enlarging or shrinking the graphic. 700-900 pixels is a commonly good range, depending on the original and its contents–you want the text (if any) on the image to be about the same size as the Confluence page text.
- Smaller original images might still be very readable but will be naturally smaller in size, which is fine. Use good judgment; look at examples in existing help manuals on this site.
- The little presized blue squares and "original" button be used too, if they work for your purposes.
- Click "Border" to add a thin black border around the image margins.
- Click on "Link" to link the image to another page or item.
- Click "Effects" to add an image effect ("curl shadow" is shown below, with a border).
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:
- In the editor, click Insert > Other Macros > Confluence Content
- Choose the Attachments macro at the top, set any parameters, then click "Insert"
- The Attachment macro tag will appear on the edit page.
- Click "Save" when done.
Looks like this (notice that the attachments embedded throughout this page are displayed here):
If you just want to add just one attachment, or embed attachments in-text:
- In the editor, place your cursor where you want to insert the file.
- Click Insert > Attachment
- Choose a file to upload.
- Change the "Link Text" if desired (default is the filename, used in this example).
- Click "Insert"
- A link to the file will appear on the page, e.g.: Confluence_UsingTheEditor.docx
If there also is an Attachment macro on the page, each embedded attachment will automatically be uploaded to it.
Links work much like individual attachments:
- In the editor, place your cursor where you want to insert the link.
- Click the "Link" button on the editor toolbar.
- Choose the type of link (from Search, Recently Viewed, Attachments, Web Link, or Advanced [insert a link into the page]).
- Follow instructions to find and upload the link.
- Change the "Link Text" if desired (default is the URL or filename).
- Click "Insert"
- The link appears on the page (gave this example a name), e.g.: Confluence Help Page
- When you use a numbering or bullet format, by default there is no line space between listed items. To add them (and once all the items are listed), go back to the end of each item and the sentence leading into it, add a soft return: <<Shift>+<Enter>.
Sometimes the items are brief enough that the extra spacing isn't necessary. For longer bits, though, the space between the dense text of listed items is helpful to readers. And BTW, this spacing here took two soft returns. THEN the next hard return gets the bullet below, but at the end of this sentence I did add one more soft return at the end of this sentence to add the extra line space.
- Numbering is thrown off whenever a hard return occurs between numbered items. Sometimes when you drop in a chunk or document's worth of content (say, from Word) onto a Confluence page, the blank places where images are supposed to be will mess up the continuous numbering of steps, for example. What I have done is to get all the numbered text together, with each item following the next, then go back in and use the soft returns to add images or note callouts. That way you can get each numbered item to follow (with a hard return and pulling text into each proper number spot) so that the numbering scheme works, THEN go back and add the interwoven figures and notes...using only soft returns to preserve the numbering.
- If this is confusing just play with it.