Properties and Sections

The projectdoc Toolbox uses Confluence page blueprints to implement 'document types' or 'doctypes' for short. A document type defines the properties and sections a document instance may provide.

For instance, the topic doctype provides properties to specify the audience, the authors and tags for the topic document. There is a section for the description and for references to further information on that topic.

Authors always have the option to add any properties or sections they require to create their documents. And if your team decides to add a property or section, simply add it to the Confluence page blueprint. The team is always in control of the structure to react to changed requirements or new insights. This is called agile documentation: document according to your needs not according to templates.

Document Types

A document type does not stand for its own. There are a number of document types that build a web of information.

For instance, the audience property of the topic doctype references role documents that describe the roles the intended readers of the topic document have. The authors property references person documents that provide additional information about the authors. This includes a list of resources referenced by the wiki the person is author of. There are references to tags and a list of references to other resources.

This is only an example. Real doctypes provide much more properties and sections.

Guided Writing & clutter-free Reading

The projectdoc Toolbox is not about defining templates and urging the authors to fill it out as a form. Its about guidance by templates. If an author wants to add a piece of information, the doctype provides a location where to put it. If the author is unsure what additional information may be provided, the doctype shows properties and section the team has decided to be most useful.

Once the document is saved, the lines with empty property values or empty sections are not displayed. Readers want to get the information that is there quickly and do not want to be distracted by column and section headers with no information.

But once an author decides to contribute to an already existing document, the properties and sections of the template are still there, helping to add the information at a location, readers would expect it to be found.

Dynamic Lists

Working collaboratively on a documentation, there is no way to manually add elements to a list of references. You need means to help to keep changes locally. So if you add a document, you tag it and expect to have your new document listed in references lists all over your wiki automatically.

Dynamix Lists are macros that do exactly that: List documents that match certain constraints. You may select documents by any property and some additional meta information (such as creator or modification date).

Single Sourcing and Transclusion

To collaborate successfully with a team, it is important to modularize your documentation. Each information should be read from a single source and redundancy is added at the teams discretion. The information is then transcluded. The projectdoc Toolbox provides macros to transclude sections, marked content or properties from documents.

There are also macros to transclude texts or images from remote information servers (e.g. to show a text snippet from a file on your source code repository or create a reference to a method in your API documentation).

Macro Structures

The projectdoc Toolbox regards templates as micro structure and the organisation of documents as macro structure.

A space in Confluence has a homepage. If you create a new document with a wizard, Confluence automatically collects documents of this type on an index page (not shown in the graphic). The projectdoc Toolbox adds the notion of a homepage for doctypes. A homepage also collects documents of a given type - as index pages do, but instead of listing them flat, it allows to organize them hierarchically.

The projectdoc Toolbox also allows to automatically store a new page of a given type on its doctype's homepage. This is something software developers know as a standard directory layout (e.g. the Standard Directory Layout defined by Maven). The location of a document is defined by its type. So if you have a new view document for your architecture documentation, you may simply add it to the view homepage of the software component's space.

This does not require to add all documents of a given type to its homepage. There is advantage in aggregating documents semantically and add documents as subdocuments of others. The documents will still be found via the index pages. So again, homepages are a feature to use deliberately, not a hard rule to follow.

Space Hierarchies

Confluence allows to add a new space very conveniently. Spaces are a good feature to structure your wiki. Different spaces may reuse existing documents, like descriptions of roles, tags, and categories. Therefore the projectdoc Toolbox provides the concept of delegate spaces. If you add a new role document in a space that defines no homepage for roles, the projectdoc Toolbox looks for a homepage in one of the specified delegate spaces and adds the new document to the homepage in this space.

Delegate spaces also provide access to their space properties (see Using Space Properties for details).

You may also define search spaces for a space. This is convenient, if you document a system and have components on separate spaces. A query with an automatic list will also find documents in the specified search spaces.

Easier to write

Documentation is easier to write since the projectdoc Toolbox supports templates to guide authors creating documents of a given type. The team may change templates provided as separate, free add-ons easily (as with all page blueprints in Confluence) to adjust them to their requirements.

Document type homepages help to store documents at a default location. This also makes document creation easier for new team members.

Since every document already has the basic structure of a properties table and section, it is very easy for authors to add additional properties and sections that are required specifically for their document instance.

Easier to extend

Documentation is easier to extend due to automatic lists. These lists capture new documents and reference them automatically. So if you have a list for all runtime views of a given component, new runtime views for this component will never get lost. But if your lists get to long, it will be required to arrange them manually into chunks that are easier to handle for your readers.

A document is also easy to extend with new properties or sections. If an author wants to contribute, the editor view suggests location where the new information may be added.

Easier to reuse

Writing modular, single sourced content, the projectdoc Toolbox provides macros to transclude information easily. Document properties, e.g. the author of a document or the story points of a user story, may be transcluded into other documents easily. Transcluding sections is similar easy.

Easier to navigate

Due to automatic lists, referencing other documents that is related to a particular document is very easy. Most templates automatically add properties or sections with references to related information.

In addition to that, the document type homepages are also easy to find in a wiki space and help users to explore your documentation.

Easier to search

Due to document properties documents are easier to find. The properties may not only be used in the projectdocToolbox's macros (such as automatic lists). Every property value is added to Lucene. This way you may use the properties also in your manual searches via the search box.

Easier to read

Using templates often lead to documents that are cluttered with empty sections that are hard to read. The projectdoc Toolbox hides empty sections and therefore makes the task of reading documents very convenient.

There are other means like glossaries and text boxes that also help to make reading documentation easier.

Easier is not always easy

Writing good documentation that is easy to read, easy to navigate and easy to find is hard. The projectdoc Toolbox provides macros and document types to make this task easier, but unfortunately, writing is hard.

Writing is hard work. A clear sentence is no accident. Very few sentences come out right the first time, or even the third time. Remember this as a consolation in moments of despair. If you find that writing is hard, it's because it is hard. It's one of the hardest things that people do.

William Zinsser. On Writing Well

Now you have completed the first introduction to the projectdoc Toolbox. From here you may

• continue with the getting started resources
• continue with the projectdoc screencasts
• jump to the homepage of projectdoc for Confluence
• or delve into the documentation for version 1 of projectdoc for Confluence

And in case of any question regarding the projectdoc Toolbox, please get in touch!

Have fun!