Blog

 

 

 

Lost in wiki space? Blank-Wikipage-Syndrome? Where to add? How to find? No fun anymore?

projectdoc teaser

Our claim is that projectdoc enhances your documentation experience as a team. projectdoc is based on projectdoc documents. A projectdoc document is a Confluence page using document properties and sections. This is contrary to starting every page with the Confluence blank page, which seems fast and easy.

You now may wonder –

The big Question

Does this additional effort actually pay off?

We say –

Our Answer

YES!

Let's check our arguments ... (TL;DR)

Your Investment

Let's first have a look on what your investment is. Who has to do what at which time?

Defining a Document

This is what you have to do to define a projectdoc document:

  1. Add the Document Properties Marker Macro to define document properties
  2. For each section of your document use the Section Macro

Who's Work and when?

The page author usually selects a page template with a blueprint wizard. So there is no need to add the properties or section macros manually.

The template author adds the properties and sections at the time she designs a template. This is a one time effort and employing macros instead of text makes not much difference.

If the page author adds a property, this is a new line in an existing table. Nothing to worry about. If the page author wants to add a new section, she may choose to not use the Section Macro. In this case the content cannot be transcluded. That's all. If the author wants to support transclusion, she has to select some macro anyway. So there is no difference in using projectdoc macros or macros provided by other vendors.

So we think the additional effort on using projectdoc macros to define projectdoc documents is quite low.

Everybody's Darling?

You have to invest in learning projectdoc.

If your authors like to invent a new document structure for each document they write and feel limited by the use of templates, then projectdoc might not make them very happy.

projectdoc leaves room to adjust documents to present the information. It does not demand to follow a defined template. To the contrary, the template is a best practice to write documents of a given kind. So adding new properties and sections and not specifying ever property and filling out every section is fine. Actually it is the responsibility of the author to decide which information makes sense. But if an information is required to meet the reader's expectation, the template defines where she expects it to be found.

So if you think templates make the task of documenting for collaborating teams easier –  and you won't be alone with this assumption – projectdoc is for you!

The Impact on your Work

Once you build your documentation with projectdoc documents, you can rely on the following features.

Select Documents

With properties and sections defined in a document, authors may employ the autolist feature (e.g. the Display Table Macro) to select and list documents.

Select documents by their properties and display properties and sections of the selected documents.

The impact of this feature on your work is better navigation, since links that refer to related information are collected and displayed easily. New pages that match the constraints will be added automatically without having to edit the referring page. This increases maintainability!

Transclude Sections and Properties

Modular documentation supports reuse and collaboration for your team.

Transclusion of information (i.e. include information from another page) supports single-sourcing (i.e. have information in one and only one place).

Use the Transclusion Macro or the Transclude Documents Macro to transclude sections and the display property macros (e.g. Display Document Property Macro or Display Document Properties Macro) to transclude property values.

A document transcludes information (properties, sections, and page fragments) from other documents.

The feature impacts on easier collaboration. Smaller documents are more easily written and maintained independently. This supports teams to create documentation collaboratively. In addition to that information fragments may be transcluded at multiple locations, which again supports maintainability since changes are applied at one location.

Conclusion

The investment in time to define properties and sections to create projectdoc documents is rather small. Furthermore most of the time effort is spent once at design time by the template author.

The investment in time to learn projectdoc, especially to learn about macros involved to render automatic lists and to use transclusion, is probably much larger. Fortunately this is also a one-time investment.

What you gain:

  1. Automatic lists of matching documents
      - making navigation and maintenance much easier
  2. Support for modular documentation based on transclusion
      - making collaboration and reuse much easier

We think the reward is larger than the investment. Do you agree?

Further Reading

For more information on projectdoc, please visit

projectdoc Introduction
A short introduction into the concepts and features of the projectdoc Toolbox.
projectdoc Document
projectdoc is based on projectdoc documents. Creating a projectdoc document is easy: A projectdoc document is a Confluence page using document properties and sections.
The projectdoc Toolbox for Atlassian Confluence
The projectdoc Toolbox supports agile teams in writing project documentation collaboratively. This is an introduction to use cases for and features of the projectdoc Toolbox.
projectdoc Toolbox Online Manual
The online manual for version 1 of the projectdoc Toolbox for Confluence.


Link

Link

Posts

Tagcloud

Loading tagcloud ...