Lost in wiki space? Blank-Wikipage-Syndrome? Where to add? How to find? No fun anymore?
projectdoc - as an add-on for Confluence - supports teams to communicate. Effective communication is essential for successful team work. Stakeholders communicate with each other and their future selves.
projectdoc focuses on indirect communication that is based on documents and records. We call the whole collection of these artifacts documentation.
projectdoc claims to support teams to create documentation that is
- easier to write
- easier to extend
- easier to reuse
- easier to navigate
- easier to search
- easier to read
Communication may be direct or indirect. Direct communication (collaborating on a user story map or talking to a customer) is usually preferred, because of its interaction options and its additional non-verbal channels.
Indirect communication (software architecture document or error codes report in a user manual) also has their benefits:
- it easily scales
- it works well with distributed teams
- it makes knowledge available on the long run
- it allows to be digested at the reader's pace
Certainly this is a big claim. Can we proof it?
Let's take a tour to the basics of projectdoc and explain why projectdoc makes using a wiki as a tool for team communication and collaboration much easier.
Here is the outline of this article:
Basics
projectdoc Document
Every projectdoc page consists of two types of information: properties and sections. A Confluence page that contains properties and sections is called a projectdoc document.
Properties help to organize documentation by classification. They contain data and metadata about the information of the document. There are properties every document should have (e.g. name and short description). Other properties are optional (e.g. audience or sort key). Some are type specific (e.g. story points or resource type), some are globally used (e.g. tags and categories).
Sections organize the content of the document into referenceable units of titled text blocks. They can be transcluded and easily moved around (per drag-and-drop) within a document. Section do not get displayed until they have content in it. That is a great feature in combination with templates, as we will find out in the next section of this article.
Here is an example showing the documentation for the tag named JSON in the page editor.
The Document Properties Marker Macro contains the document properties in form of a three-column table. In the example the following properties are shown: Short Description, Doctype, Name, Parent, Audience, Tags, Categories, Iteration, and Sort Key.
The sections of this document are Description, Subordinate Tags, Documents, Notes, References, and Resources.
You still may add any content to a page. Content is not required to live inside sections. Even with projectdoc Confluence is still a wiki.
projectdoc documents support
- easy writing by movable sections and a fixed structure on where to put properties and sections
- easy reuse by transclusion of property values and sections
- navigation and search by document properties (and some macros we introduce later)
- reading by not displaying empty sections
Doctypes
Doctypes define the properties and sections available for a document of a given type. They are basically templates that are implemented as Confluence Blueprints.
Doctypes reference document instances of other doctypes. The Audience property may reference Role documents or the Tags property lists references to Tag documents.
Since sections are only rendered when they have content, authors do not have to eliminate the sections they are not using right now. The guiding structure of the template is not lost for future additions.
The structure is not very strict. Confluence is a wiki after all, so we need some freedom to evolve. New properties and sections may be added at any time to the document instance.
projectdoc provides some suites of doctypes as free add-ons. Furthermore theses add-ons are available on Bitbucket so that you can download the source code and customize them to your needs.
projectdoc is not about providing templates for use. Your templates are your tools that have to match exactly your requirements to be most effective and efficient. Therefore it is unlikely that a given suite of templates fits your needs.
Instead, projectdoc is a set of tools to help you defines your templates. See the free add-ons not as a product to use from the shelves, but as a basis to design your own. While it is certainly feasible to use templates that do not touch the heart of your productivity as is, we encourage you to adjust the templates you work with every day to fit your needs as closely as possible.
If you have suggestions on improving the standard templates, just get in touch. We are continuously evolving our templates.
You are not limited to the document types we provide with our examples. Using properties and sections allows you to define any doctype you need for your team's communication.
The following sample document is an instance of the Tag Doctype. It is the same as in the example before.
The Document Properties Marker Macro contains the table with property names (first column), values (second colum), and controls (third column). Keys are plain values and the hide control will suppress the rendering of the property even if there is a value specified.
The section Documents will render all documents tagged with JSON automatically. See the next section of this article for details on automatic lists.
Since only a few properties are specified and no section contains text, the rendered document is quite short.
Once you start adding more information as properties and to the sections, the document is rendered like this:
If you have defined a Category document called Format, the property value of Categories will render a link to that document automatically due to the use of the Name List Macro.
projectdoc doctypes support
- writing by proving guidance with templates
- extension by allowing to define any template you need
- reuse by creating new documents with blueprint wizards based on your templates
- reading by enforcing a team-defined structure on every document of a given type
Automatic Lists
Be open for extension, but closed for modification. The open-closed principle for software development has its benefits also when applied to documentation. That is, if you add a new document any changes should be done to that document and not to existing documents.
For instance, if you define a document that lists all error codes logged by your application, you should not need to open the document with that list and add an additional code. Instead you define an automatic list in the document that collects all documents of type code and - as an example to show you how to further constrain the query result - tagged with public API. From now on every new code document you add to your documentation and tag with public API will be automatically listed. You may select on any property you have defined in your Code Doctype.
Every team member should focus on creating new documents and reuse existing information. This results in a modular documentation that supports collaboration.
This example shows the Display Table Macro on the Tag document of the previous example. It selects the properties Name, Short Description, Tags, Doctype to be shown in its columns. The where clause selects on the Tags property that is equal to this document's Name property. If you would specify the query manually, you would probably use the following syntax:
$<Tags> = [Tag]The somewhat unattractive syntax pretends that the query must use exact match. If this is not the case, use this (which is more easily understood):
Tags = TagFor more information on query syntax, please refer to Search Tips.
projecdoc automatic lists support
- writing by defining queries on documents
- extension by automatically collecting documents that match the specified search criteria
- navigation by displaying links to related resources on a page
Transclusion and Referencing
Every information is stored in a system that is best in working with it. There is never a one-size-fits all. You may store your stakeholder address information in an SCM and your source code in an LDAP. But the other way round may make more sense in most cases.
We strongly believe that there should be one access point for a project. That single address every stakeholder - be it the project sponsor, the team member, the customer, the user or any other interested party - remembers and finds access to the information she is looking for.
We suggest to use a wiki as this single point of access. Wikis are easy to add new information or to restructure the organization of your information quickly. This is important to adopt your tools to the way you want to work. Your mileage may vary.
There may be reasons to separate the information systems that provide access for different users, especially security or performance concerns. But we think that these requirements have to exist to define different access points. For small projects a single access point is typically the organization of information you should strive for simply for simplicity reasons.
To make information from remote resources available in a wiki, you need tools like transclusion and references. Transclusion grabs a part of a document and renders it within another. A reference is simply a hyperlink to an information in another document.
projectdoc provides a couple of macros for transclusion and macros for referencing.
The example shows the Transclusion Macro that transcludes the Documents section of the JSON Tag document we introduced before. Note the border around the section. It is rendered only to users with write access and makes it easy to identify transclusions and navigate to the transcluded document.
projectdoc provides even more macros to transclude information (e.g. Transclude Documents Macro or Display Document Property Macro). There are also a number of macros to reference information, like the Javadoc Link Macro (to reference information in a Javadoc API), the Enterprise Architect Image Link Macro (to reference macros generated with the Enterprise Architect Maven Plugin), or the External Link Macro.
While referencing is fairly simple, transclusion may demand some extra calculation power. Check your target information architecture with your hardware thoroughly before you roll it out!
projectdoc transclusion and referencing support
- writing by reusing existing information
- extending by incorporating existing parts and add new information to that context
- reuse by showing existing content in different locations
Delegation and Search Spaces
Sometimes the organization of pages in page trees within a space or in different spaces just is not enough. There is the need to arrange spaces and search information in a space group. You may also want to delegate the location of a new page to a space that is responsible for organizing this type of information for several teams.
projectdoc provides the concept of delegate spaces and search spaces. A projectdoc space provides standard locations for standard information. Software developers know this approach well: if they use Maven they do not need to worry about where to look for Java sources, site information, or scripts. It's a convention, but reasons for not following them are very rare. The same approach is used to store view, use case, or minutes documents. There is a standard location known as doctype homepages. If you want to collect documents of a given type for a space in another space, you define that space as a delegate space. That is, if you create a document and want to send it to its standard location, this location is first looked up in the current space and - if that homepage cannot be found, the list of delegate spaces is traversed until the homepage is found.
If there is no homepage defined, the standard location is a child of the current page.
A search space reference extends the search of projectdoc macros. Not only documents of the current space are considered as matches, but also spaces found in the search space closure defined for that space.
Delegate and search spaces are defined as Space Properties, typically on the homepage of the space.
projectdoc delegation and search spaces support
- writing since doctype homepages make it easy to add new documents
- extension due to adding existing spaces via delegation and search to new spaces
- reuse of information in existing spaces
- search of information in different spaces (note that there is currently no search macro that automatically expands the search space, so this feature is applied only to projectdoc macros)