Blog

  • 2024
  • 2023
  • 2022
  • 2021
  • 2020
  • 2019
  • 2018
  • 2017
  • 2016
  • 2015
  • 2014
  • 2013
  • 2012

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

projectdoc is based on projectdoc documents. Every projectdoc document defines properties and sections. This is contrary to starting every page with the Confluence blank page.

If you consider to use projectdoc to enhance your documentation experience as a team - as is our tagline - you may ask:

Panel
titleThe big Question

Does this additional effort actually pay off?

We say

Panel
titleOur Answer

YES! 

- and here are our arguments!

Section
titleYour Investment

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

Section
titleDefining 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

Section
titleWho'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 defines template. This is a one time effort and employing macros instead of simple 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 effort on using macros is quite low.

Section
titleEverybody's Darling?

You have to invest into 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 adding 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.

Section
titlePayoff - the Features

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

Transclusion
taget-heading-level2
documentPDAC1:projectdoc Document
idsSelect Documents

Transclusion
taget-heading-level2
documentPDAC1:projectdoc Document
idsTransclude Sections and Properties

Section
titleConclusion

We showed that the investment in time is rather small and the benefits are automatic lists and the ability to support modular documentation using transclusion.

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

Section
titleFurther Reading

For more information on projectdoc, please visit

Tour
render-as-definition-listtrue
replace-title-with-nametrue