A short introduction into the concepts and features of the projectdoc Toolbox.
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
- more than 85 macros
- conventions to improve project documentation (e.g. provide short descriptions)
- page blueprints called doctypes (30+ in the Core Doctypes Add-on and more in doctype add-ons)
- space blueprints (part of doctype add-ons)
- extensions to further extend the use cases of the projectdoc Toolbox (for instance Web API, Information Systems)
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.
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.
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.
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.
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.
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.
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).
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.
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.
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).
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.
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.
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.
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 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!
More information for new users to get started with the projectdoc Toolbox.