Confluence - Best practices for application template creation

[Sylvain PINGONT]

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.

[Robert Reiner _smartics_]

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

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

The tools confluence provides to implement these features are:

1. Add Metadata: Page Properties Macro and Page Properties Report Macro
2. Content Reuse: Excerpt Macro and Excerpt Include Macro
3. 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:

1. Add Metadata: Document Properties Marker Macro, Display Document Property Macro (and other display property macros)
2. Content Reuse: Section Macro, Content Marker Macro, Transclusion Macro, Transclude Documents Macro
3. 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!

[EPS Software Engineering AG]

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

[jabybit]

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

[EPS Software Engineering AG]

Hi Sylvain,

We asked the same questions back in 2013. Templates are ok, when you have only a few. If you have dozens, then the dialog to choose is a pain. And templates are limited to one page. Blueprints support multi page templates, but you have to write a plugin.

This has meant, that we have developed our own plugin, with which templates and bluerpints are created easily and very rapidly. And for the end user the usage is also very simple - pressing a button and filling out a form.

Try it for free under:

Marketplace link: Page Tree Creator

Regards,
Stephan

[Sylvain PINGONT]

Hello and thanks for your reply, but it's not exactly the answer i'm expecting 

More advice on how to create the most appropriate template to manage our internal application information catalog, such as key requirements, information that are mandatory to display and way to optimise the display.