The latest version, 1.1.0, of the Project Documentation Macros add-on for Confluence provides the Section Macro. This macro allows template authors to create templates that guide authors creating document, while readers are not distracted by empty sections.
The macro basically provides title and a body. If the body is empty, the section will not be rendered. In edit mode the structure of the document is visible to the page author. In view mode the document shows only sections with actual information.
The add-on (version 1.1.0) is available on the Atlassian Marketplace.
Example: Macro Doctype
Here is an example with a doctype that is defined to document macros. The doctype specifies the following section in the given order. This makes it easier for document authors to document a macro.
- Description
- Properties
- Details
- Related Macros
- Sub-Macros
- Notes
- References
- Resources
In the editor view the document is shown like this:
Every section is rendered so that the author knows about the information that is expected in the document type. The author is not required to fill out every section.
Please note that the screenshot is taken from the commercial version of the Section macro. The view of the open source supports only the standard representation of macros.
This is due to licensing restrictions of Confluence source code we use to render the headings.
In view mode the sections containing no information are not rendered. So readers do not have to read sections that contain only headings (or information that resolves to nothing). But the structuring information is still there and will be visible again, once an author starts to edit the page again.
The following video shows the Section macro in action:
projectdoc
The section macro is also part of projectdoc, the commercial variant of this free add-on. Since projectdoc provides a feature called space properties, the projectdoc Section Macro has some more features to control the appearance of the sections. Sections are also used for transclusion in projectdoc.
projectdoc Toolbox
If you want to learn more about the projectdoc Toolbox and how it helps to create good project documentation, please refer to the introduction video!
The following image is a link to a video on YouTube. When you click the link your browser will serve a page from youtube.com.
Very interesting, but way too fast?
Step through at your own pace with with our Prezi Presentation (external link to prezi.com)!
In the Online Manual you’ll find additional video material that introduces you in the concepts of the projectdoc Toolbox.
Refer to use cases and show cases for information on how to use the projectdoc Toolbox.
