projectdoc Toolbox

Use or define page blueprints with properties / metadata and sections that render only if they actually contain information. Use or define space blueprints with homepages for document types for dynamic organization.

In order to stop the Blank-Page-Syndrome authors need to know where to put a piece of information. Therefore they need to locate

  1. the appropriate space
  2. the appropriate location within the space
  3. the appropriate document type / page blueprint

The wizard of the selected page blueprint will then guide the author to put the information where the reader will expect it to be.

This article explains how the projectdoc Toolbox support the organization of information on the microstructure (page) and macrostructure (space / entire site) level.

Form follows function. So authors usually expect freedom on how the document is structured to pass the information effectively to the reader. But on the other hand the reader expects similar information to be presented similar. The reader should also not notice which author has actually written the document.

Therefore authors need tools to help them to align the new document with the existing documentation and the expectation of the readers seamlessly. A template can help. But we must not force the authors to follow the structure of the template mindlessly. The authors are still in charge to create the structure that delivers the information best, but the template is a guide to allow the authors to follow if no better solution is at hand.

Here are some structures a template defines that are usually best kept in sync with other documents.

  • Properties of document types
    • Names of properties
    • Values of properties
    • Order of properties
  • Sections of document types
    • Name of the sections
    • Order of the sections

Usually these rules can be followed without any negative influences on the readability.The authors must not be forced to follow this structure. If a value of a property is not available and not important for comprehension, it must be left off. If a specific section is irrelevant or may not provide further understanding, it is important to leave it blank. Do not add any decoy text. If a paragraph, sentence, or even a single word does make the point clearer then drop it. In some cases it may also add to the understanding of a document, if sections are set in a different order or the content of several sections is written to one with an individual title.

Last but not least we are not writing to win the Pulitzer Prize for literary achievements. There are certain kinds of documents that are best consumed if they follow a rigid structure. Glossary items do not gain much appreciation if every entry presents its information in an arbitrary sequence. Meeting minutes are best parsed by readers if they follow a predefined structure. Every document that comes in numbers, that are aggregated in a number of views benefit the reader if they are similarly structured.

Homepages to store Documents

Each template is defined by a doctype that defines the basic structure of every document instance of this type. The structure is a compilation of properties and sections.

In projects documents of the same type tend to be accessed together. Think of documents that describe roles or personas. Or design decisions, meeting minutes, the documentation of aspects of a software architecture. projectdoc defines a default location called homepage for each (with some exceptions that should not bother us here) document type. The homepages are similar to index pages you may already know. There is only a slight difference. While index pages collect every page that has a certain label on it, the documents on the homepage are the most important documents of that type. There may be more documents that are children of these root types. Think of roles! There may be a role document that describes the most generic user of a system. Subdocuments of the User document may be specialized users, like Power User or Admin User. The homepage only has a reference to the User document and allows the reader to drill deeper into the hierarchy step by step. If the user needs an alphanumeric listing of all roles, the index page is still around. But the documents are typically not stored on the index page, but as pages of the homepage or as a descendent of one of the root documents of their type.

If you create a space, all homepages are created by default. The space homepage lists references to the homepages (either directly or indirectly).

Here is an example from a space created by a projectdoc space blueprint.

The 'Topics' link on the space homepage refers to the homepage of the Topic doctype. There is one document instance on this homepage called 'Installation Howto'. On the homepage there are more links to homepages of doctypes (for instance Tours, FAQs, and Glossary). If a team defines a basic structure for their spaces of a given type, new group members, who have worked with other teams on other projects, will have an easier time to get familiar with the domain of a new project. They still have to learn the new domain, but they are already familiar with the structure of the documentation for this domain.

Default Target to store Documents

Each page wizard for a doctype that supports a homepage, there is a flag to store the document either as a child to the current page (default) or to send it to the homepage for this type.

The screenshot shows the creation of a document for a role named 'User'. The author decided to store the document to the homepage of the 'Role' doctype instead of saving it as a child to the current page. The current page is the page the author viewed when she decided to create a new page by starting the wizard.

Delegate Spaces and Homepages

Some documents are relevant to more than one space. If you have a large project with multiple large components you may want to have a space for each component you describe. Each component may share the same roles and topic types. So there is no need to have them copied around spaces. Instead have them stored in a collaboratively used delegate space.

There may be more than one delegate space. Delegates spaces are specified in an ordered list.

Whenever an author sends a document to its doctype homepage, the document is stored to the immediate homespace page found in the delegate space hierarchy. Assume for instance that the current space has a delegate space with a homepage for roles, but has itself no such homepage. If a document of type 'Role' is sent to its homepage, then it will be stored on the role's homepage on the delegate space.


More information to get started with the projectdoc Toolbox:

  • projectdoc Toolbox Online Manual - The online manual for version 1 of the projectdoc Toolbox for Confluence.
  • projectdoc Introduction - A short introduction into the concepts and features of the projectdoc Toolbox.
  • Hands-on Tutorial - Get started with the projectdoc Toolbox: learning by doing
  • Introduction for new Users - Provides information to get new users of projectdoc get started with projectdoc documents and spaces.
  • Basic Concepts and Conventions for projectdoc - Concepts central to projectdoc. Things users have to understand to get the most out of using projectdoc.
  • Tours - Guided views on topics for different audiences.
  • Doctypes - Doctypes define properties and sections for documents. They are essentially Confluence Blueprints that help to create pages in your wiki based on templates.

More information on macros used in the examples.

  • 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.
  • Document Properties Marker Macro - A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
  • Wiki Link Macro - Allows to render a link to a wiki page.