A short introduction into the concepts and features of the projectdoc Toolbox.

Level of Experience
Expected Duration
5 minutes

Watch this screencast on YouTube (please not that this video has sounds on, just in case you are in your office):

Step through this presentation at you own pace: Prezi presentation.

The pace of the video is very quick! This gives you an overview over what the projectdoc Toolbox is all about in a very short period of time. The rest of this article explains the topics you have watched in this video.

This introduction provides information on the following topics:

What is the projectdoc Toolbox?

The projectdoc Toolbox is a collection of

How is projectdoc different?

The projectdoc Toolbox is an add-on for Confluence. The add-on fits to the Confluence conventions and improves your team's collaborations experience.

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.

A Document Type defines Properties and Sections The Topic Doctype with some of its Properties and Sections

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.

Related Information

Document Types and Templates
Document types (or doctypes for short) define a set of properties and sections. Each doctype matches at least one Confluence Page Blueprint. Confluence Page Blueprints are a collection of templates, but often the collection contains only one element.
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 Types

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

A Web of Documents

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.

 

Please notice that the projectdoc Toolbox is not about the doctypes we have shown above. The projectdoc Toolbox is about defining doctypes that meet your requirements. You may

  • use the doctypes we present with projectdoc as is,
  • use them as a starting point to define your own,
  • or start defining your doctypes from scratch.

The projectdoc Toolbox provides macros to help you define your documents within your Confluence wiki based on properties and sections. Plus a lot of macros to help you add navigation to your modular documentation.

Related Information

Macros
List of macros provided by the projectdoc Toolbox.
Doctypes
Doctypes define properties and sections for documents. They are essentially Confluence Blueprints that help to create pages in your wiki based on templates.
Tour for Template Authors
This is a tour through the documentation for users that want to design their own set of templates or just want to create one or two templates.

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.

Edit Mode and Read Mode - two Sides of a Doctype

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.

 

Authors may at any time add additional properties and sections. Since these are not part of the template, other authors may add similar properties and sections to their documents, probably at different locations.

So be cautious to add properties and sections to a document, if you consider them to be part of the template in first place. Talk to your documentation architect and your team to extend the template.

Related Information

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.
Content Marker Macro
Marks a piece of content within a document. This content can be referenced for transclusion.
Document Properties Marker Macro
A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.

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.

Automatic Lists select Documents 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).

 

Use dynamic lists to enhance the navigation in your wiki. A short description is required for every document. Use dynamic lists to render the name of the document as a link and the short description of that document to help readers decide which link to follow.

Related Information

Display Table Macro
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
Display List Macro
Lists references to projectdoc documents in a list. List contain names and optional short descriptions.
Transclude Documents Macro
Renders transcluded content fetched from documents of a result set.

Have a look at the Tour Macro, if you require to control the elements and their ordering of a list.

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.

Transclude Sections, marked Content, or Properties

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).

Related Information

Modular Documentation
Use rich multi-excerpts (transclusion) for content reuse - even from page result lists. Replace parameters in excerpts. Include properties and sections from pages. Hide content dependent on roles and properties.
Transclusion Macro
Transcludes content from a document marked with the content marker macro.
Display Document Property Macro
Renders the value of a property of a document.
Display Document Properties Macro
Renders a template with property references.
Modular Documentation Macros
Macros to support single sourcing for creating modular documents.

Macro Structures

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

Macro Structure with Home Pages

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).

Space Hierachies with Delegate and Search Spaces

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.

Related Information

delegate-space
List of spaces to delegate documents on creation to. Also works as a search space for upstream spaces.
search-space
List of spaces to include in downstream searches. Use @all to refer to all spaces.

With projectdoc your Documentation is ...

This has been a quick rush through the concepts of the projectdoc Toolbox. Using the toolbox's macros to work with documents based doctypes, your documentation is

  • easier to write
  • easier to extend
  • easier to reuse
  • easier to navigate
  • easier to search
  • easier to read

And it is still based on rules and constraints defined by the team.

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.

 

Note that there may be performance constraints to transclusion! Please test your documentation architecture on your machine to know the limits of your hardware!

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

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

Have fun!

Resources

 More information for new users to get started with the projectdoc Toolbox.

Think big, start small
Starting with the projectdoc Toolbox might be intimidating at first. So start small using the basic features and add what is needed, when it is needed.
Introduction for new Users
Provides information to get new users of projectdoc get started with projectdoc documents and spaces.
Finding without Searching
The goal is to learn how to organize project information effectively. While we aim at software developers with the need to document their projects, software and system architecture, this article is probably also relevant for other teams that work on other kinds of projects collaboratively.
Hands-on Tutorial
Get started with the projectdoc Toolbox: learning by doing
Evaluation Topics
Provides information about features potential users should consider for their evaluation process on using the projectdoc Toolbox for Confluence.
Tips
List of tips to use Confluence with projectdoc and fun!
Tours
Guided views on topics for different audiences.
Macros
List of macros provided by the projectdoc Toolbox.
Doctypes
Doctypes define properties and sections for documents. They are essentially Confluence Blueprints that help to create pages in your wiki based on templates.
projectdoc Extensions
Extensions augment the projectdoc Toolbox. Features that are not relevant for all users are separated and may be installed on-demand by customers of the Toolbox.
Topics
A list of articles that provide information on design principles and conventions of projectdoc.
Glossary
Terms used in and defined for projectdoc.
FAQs
Questions and answers related to the projectdoc Toolbox and Confluence.
Agile Documentation
Information on agile documentation: from values to principles and practices. A set of actionable tools for team communication.