In the first short article of this little three-step tutorial we introduced the concept of the space and page blueprints briefly.
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.
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 or does not have related articles, 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 is to use 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 and additional information will be added soon.
Here is the content in the editors. On the left you see the Howto of Confluence, on the right the Topic of projectdoc.
This example is not about the contents of the documents. It is perfect to design a howto with a concise representation of a numbered list of steps. 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.
So, we do not want to discuss the perfect howto article structure here. We want to point out techniques that allow to guide writers to create documents and not clutter 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. 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 is defined. This is more troublesome if you provide a larger number of sections to guide authors on what information may be added.
Once you add content to the section, the section will automatically appear.
The following screenshot shows three sections, two of them with text content.
On saving the page, the two sections with content will be rendered.
There is still no abstract, so this section does not show up.
