projectdoc Toolbox

Despite the name of the Topic Doctype, it is not supposed to be used for any topic. Use the Generic Doctype or the Section Doctype for general purposes.

Parent
Audience
Level of Experience
Expected Duration
15 min
Type

Templates are a powerful tool to create and organize information for projects and products as a team in your Confluence Collaboration Platform.

The projectdoc Toolbox supports teams to define their own set templates. smartics also publishes sets of templates as Doctype Add-ons on the Atlassian Marketplace to get teams started. Since we do not assume to meet every requirement and minor tweaks may tremendously improve team performance and fun, these templates are also available on Bitbucket under the Apache License 2.0.

Creating templates requires none-the-less considerable resources. In case you need to document a set of a dozen documents, creating a new template may not be the way to go. Instead you want to create a document prototype and copy it twelve times. This tip shows how this can be done.

Contents

Template, Blueprint, Doctype - really confused?

A template is used to create pages in Confluence. It defines a basic structure that is added to a page at the instance it is created. There is no connection between the page template and the page instance. Changes to the template will therefore not be reflected to the pages created by using this template. More on templates...

A blueprint is a set of templates (although typically only one). This is a tool provided by Confluence and typically there is also a wizard that supports users to create pages of a particular type. Confluence provides index pages that list all pages of a given type. The type is added as a label to the page index. More on blueprints...

A doctype is a blueprint that is a projectdoc document. It therefore provides properties and sections based on macros found in the projectdoc Toolbox. Pages based on doctypes are therefore called 'documents'. More on doctypes...

Summary

If you have a limited number of instances of a given document type, it typically does not pay of to define a template for it. Simply create one document as a prototype and copy it for each document you need.

Use the Generic Doctype (standalone documents) and the Section Doctype (sub-documents) as a base for creating the prototype document.

Templates Not to Choose

Every projectdoc document needs to provide properties and sections. It is a good idea to not start with a blank document. Otherwise there are plenty of manual steps to get all macros and their content in place.

Here are some options and the reason why you should not choose them.

TemplateReason NOT to choose

Blank page

Confluence Blank PageThe page is totally empty. You need to add the Document Properties Marker Macro for the document properties and the Section Macro for each section required for your documents.

Some properties should be provided by all documents. These include a name and a short description. To organize you documents the properties subject, categories and tags should also be supported. There are a number of other properties that probably should also be supported. The same is true for sections: often a description and a summary helps readers to find the information quickly. References and resources point to further information at other places. Having the same basic set of properties and sections at the same location in all documents help readers to find what they are looking for.


Advice: Look for a template that supports basic properties and sections.

projectdoc Blank Document

projectdoc Blank Document in Edit Mode

The projectdoc Blank Document Doctype is installed with the projectdoc Toolbox. It provides the standard properties and sections, but it does not assume that the Core Doctypes Add-on with the core doctypes like Subject, Category, Tag, Role, etc. are installed. Therefore the values (second column in the document properties table (inside the Document Properties Marker Macro) do not use the macros (like Name List Macro or Display Document Property Ref Macro) to create references to these organizing document instances.

 

Advice: Install the free Core Doctypes Add-on and take advantage of the organizing document types.

Topic

Topic Template in Edit ModeAt smartics we learned that many users choose the Topic Doctype if they want to document something generic, where no other template seems to match their needs.

Choosing the Topic template is not recommended, since it provides a number of properties and sections that are not generic. The topic template is supposed to provide information on a given topic to a defined audience. Therefore properties like "Level of Experience", "Expected Duration" and sections like "Prerequisites" are provided that do not make sense if - for instance - you want to document a contract or a certificate.


Advice: Use a template with a minimal set of properties and sections.

Template to Choose

So here are the doctypes that provide templates we recommend for generic use.

TemplateReason to choose

Generic

Generic Template in Edit ModeThe Generic template provides all properties and sections commonly used. Documents of this type are intended to be top-level, but they do not provide a homepage for the types of this document. There is an index page that lists all documents of this type.

You may replace the value of the Doctype Property with the name of your ad-hoc doctype. But this will not create a new doctype. Doctypes need to be implemented by blueprints. By changing the value of the doctype property only this value is changed. This may be useful to select your documents by a query (for instance with the Display Table Macro). But this selection can also be made possible by introducing a new document property.


Advice: Use the Generic Doctype for documents of generic type.

Section

Section Template in Edit ModeA document based on the Section template is similar in structure to document created with the Generic template. The only difference is the name of the doctype and the creation of the page title. A section document is supposed to be a sub-document and therefore the title of the parent document is appended to the sub-document's title. Since every page in a space is required to have a unique name, sub-documents typically have clashing titles, this way of title creation enforces an easy to use rule.

Most of the time sub-documents are generic. There are some exceptions, for instance the Excerpt Doctype or Alternative Doctype.


Advice: Use the Section Doctype for sub-documents of generic type.

Resources

More information on templates, blueprints, and doctypes.

Overwhelmed with Blueprints?
Templates are a great tool to make creating and maintaining documents very easy. Blueprints support authors to create documents based on templates. But a large number of blueprints may make it difficult for authors to select the appropriate template. Here are a few tips on dealing with larger amounts of blueprints.
Views on Topics
projectdoc makes it easy to create a modular documentation and provide multiple views on topics.
Generic
Generic Documents provide information where no other doctype matches.
Section
Sections of a document are typically part of a document. But the size of sections may vary. To support a team to write collaboratively on the documentation, a larger document may be subdivided into external section documents.
Blank Document
The blank template simply provides a minimal integration with projectdoc features. It is a quick starting point to use projectdoc.
Topic
A description of a given topic. A topic may describing or explaining a concept, a task to accomplish or a reference. There are a couple of topic types that set the expectations for the reader. Instances of the topic doctype usually have independent lifetimes from any referencing documents.
Document Properties
Properties are metadata that can be added to every projectdoc document. If you require a set of metadata for each instance of a document type, you should write your own doctype.
Document Sections
The main body of a document is divided into sections. Besides the sections defined by a doctype, an author may add any number of additional sections. Sections that are regularly added to a given doctype should be added to the doctype's template.
Document Properties Marker Macro
A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
Section Macro
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.