projectdoc is based on projectdoc documents. Every projectdoc document defines properties and sections.
If you consider to use projectdoc to enhance your documentation experience as a team, you may ask yourself: "Does this additional effort actually pay off?"
We say "YES!" - and here are our arguments.
Define a projectdoc document
This is what you have to do to define a projectdoc document:
- Add the Document Properties Marker Macro to define document properties
- For each section of your document use the Section Macro
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.
Payoff - the Features
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.
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.
