In the first short article of this little three-step tutorial we introduced the concept of the Confluence space and page blueprints briefly.
One of the biggest time-saving tactics you can employ in your workplace is creating standardized content. Teams waste so much time every day creating documents from scratch or mindlessly scanning unstructured pages for the information they need. It’s time to stop reinventing the wheel.
Ryan Anderson. 3 Killer Features for Creating Awesome Page Templates in Confluence. (2013)
Blueprints are designed to get new users started quickly. Therefore they may contain instructional texts to help those new users to find out easily what to do next. For experienced teams this approach is not that optimal since users have to remove some boilerplate sections every time they create a page based on that blueprint.
The Reader's View
Here is an example from the Howto Blueprint provided by Confluence. If you launch the wizard and save, this is what you will see in your browser:
If your howto is not restricted to a simple list of steps (yet) or does not have related articles (yet), the author has to remove those parts from the page. If there is no relevant information, it would be easier for readers to not have to read anything.
To accomplish this task use projectdoc's the Section Macro. A section is a text element with a title. Only if the section actually contains text, it will be rendered. So in the projectdoc version of the howto (based on the Topic Doctype) the page would be rendered like this.
This page shows only information that is relevant to the reader. There is a short description that tells what this topic is all about and the Iteration property shows that in the Facade state only a name and a short description is provided, while additional information will be added soon.
The Author's View in the Editor
Here is the content in the editors. On the left you see the Howto Article for Confluence, on the right the Topic of projectdoc.
This is not about Howtos!
This example is not about the structure of the documents. It is perfect to design a howto with a concise representation of a numbered list of steps. This is often the most appropriate representation of a small number of action items. The projectdoc version assumes that you add a section that allows you to give examples or provide screenshots.
You may come to the point where you want both: Sections with detailed information and a table of contents that outlines the individual steps concisely. In this case you will probably define your own howto article template.
So, we do not want to discuss the perfect howto article structure here. Instead we point out techniques that allow to guide writers to create documents without cluttering the view for readers.
As you can see the projectdoc version of the howto article still shows the individual sections that guide authors to add new content (click the images to access a larger version). If you would have removed the content to not display clutter on your page, authors would have to search (or create) a howto document with the now required section to insert it where it is defined. This is more troublesome if you provide a larger number of sections to guide authors on what information may be added.
Think about Use Case documents which provide much information. Not every piece of information for a particular document is available or relevant right from the start. Documents evolve over time and may be edited by different authors at different times.
Add new Content
Once you add content to the section, the section will automatically appear.
The following screenshot shows three sections in the editor view, two of them with text content.
On saving the page, the two sections with content will be rendered. The section without content is still not relevant for the reader and therefore not shown.
Additional Tools
There are some more macros provided by the projectdoc add-on that support hiding content that is not useful to be rendered to a reader. Even more: once the content is available, the information will be rendered automatically.
| Macro | Short Description | Notes |
|---|---|---|
Marks a piece of content within a document. This content can be referenced for transclusion. | Marks an area to show only if privileges or space properties match. | |
Allows to render a link to a wiki page. | Links to pages that not yet exists may be rendered or may be suppressed. The link will show up once the target page exists. | |
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided. | A query that matches a number of documents. If no document matches, the macro is typically configured to render nothing. | |
Lists references to projectdoc documents in a list. List contain names and optional short descriptions. | Same as the table version above, but renders the hits in a list. | |
Renders transcluded content fetched from documents of a result set. | Also a query on pages to transclude that may be configured to render nothing if the query result is empty. |
With these macros authors are able to reference information that is added in the future. But as long as the referenced information does not exist, the reader is not burdened with reading page elements without information.
Conclusion
Templates are great since they help authors to create content with a similar structure. The template is a guide to overcome the blank-page syndrome and is a reminder of which information may be of interest for the readers. The template also helps readers to digest information more easily since it is presented in an expected manner.
We introduced some macros provided by projectdoc that help to create pages to support writers without cluttering the view of readers. Here is the list of all macros:
| Macro | Short Description |
|---|---|
Renders a section, if the body is not empty. Supports authors to create content, clutter-free rendering without empty sections. Allows to transclude the content. | |
Marks a piece of content within a document. This content can be referenced for transclusion. | |
Allows to render a link to a wiki page. | |
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided. | |
Lists references to projectdoc documents in a list. List contain names and optional short descriptions. | |
Renders transcluded content fetched from documents of a result set. |
The last article of this short series will have some tips on creating space blueprints. We will see some of the macros mentioned above in action.
