Confluence - Best practices for application template creation

Question

Hello the community,

I request your help, because we need to create some template to have a global overview of our applications (General information, contact, techno used, db, documentation link...).

I would like to check what are the best practices to create such template and provide a complete set of information in the appropriate way for our IT Team.

Thanks for your help.

jabybit · Answer

Yes, Brikit's presentation is fantastic! It's excellent for deployment of any tool really, nice work!

EPS Software Engineering AG · Answer

Hi Reiner,

Brikit's presentation is very good. Thanks for the link.

I think your answer covers really well. The only Macro I would add is the Navigation Map Macro.

Regards,
Stephan

Robert Reiner _smartics_ · Answer

I'm not sure if I understand your question precisely. It is quite difficult to give advice to your specific problem without details. Probably you are not asking for specific information, but for a general approach on creating an information architecture based on Confluence.

Basically you could consider the following topics

* Add Metadata - will also help your teams to define queries
* Content Reuse - mark content of a page to transclude it in other pages
* Dynamic Lists - to create navigation paths automatically by labels

The tools confluence provides to implement these features are:

* Add Metadata: Page Properties Macro and Page Properties Report Macro
* Content Reuse: Excerpt Macro and Excerpt Include Macro
* Dynamic Lists: e.g. Content by Label Macro

So you may add the page properties macro to your template and define the metadata for the type of documents to create with this template (such as product version or release date). Then you may want to mark the content (such as short descriptions or system requirements) that you plan to transclude from other pages (such as overviews). Finally you may want to add sections with related information where a content by label macro will automatically reference information labelled with a given tag.

Since you are listing information like contact information you are probably requiring multiple templates. A contact document instance based on the contact template may then be referenced or transcluded (excerpt in the Confluence terminology) in e.g. a product document instance.

You may have a look at the projectdoc Toolbox, our commercial add-on for Confluence, that provides macros for these and other use case. As a starting point these are the macros of the toolbox that align to the areas I mentioned above:

* Add Metadata: Document Properties Marker Macro, Display Document Property Macro (and other display property macros)
* Content Reuse: Section Macro, Content Marker Macro, Transclusion Macro, Transclude Documents Macro
* Dynamic Lists: Display Table Macro, Display List Macro

Personally I prefer blueprints over templates. If you are looking for examples on starting a blueprint add-on project, Confluence Blueprints is a good way to start. Also check out examples on Bitbucket. But as Stephan mentioned, this involves programming a plugin.

If you are looking for more general information, I found Brikit's presentation on Creating a Sound Information Architecture in Confluence very helpful. If you are looking for literature, I would recommend to have a look at Morville, Rosenfeld, and Arango's book "Information Architecture for the World Wide Web".

If you are searching for tools to define a documentation process (e.g. enforce mandatory information), you may need to look for add-ons that support defining workflows. For optimised display you probably want to have a look at theme add-ons such as Brikit Theme Press.

Hope this helps as a starting point!