Using sections and modules to organize and reference content.
- Audience
- Type
- Level of Experience
- Expected Duration
- 5 min
The projectdoc Toolbox provides tools to create a modular documentation, supporting Single Sourcing. These tools include doctypes and macros for transclusion.
This short tip provides a brief introduction.
Sections
projectdoc documents are defined by properties and sections. A section is typically defined by the Section Macro. Such sections can be referenced, but require the fragment identifier to do so. In order to modularize a document, sections can be added by the use of the Section Doctype and transcluded by a transclusion macro – either one-by-one using the Transclusion Macro or the Transclude Documents Macro. The section documents are typically stored as child documents to the transcluding document. Therefore the Transclude Documents Macro allows to create a document divided into section documents easily. In addition to that these section documents ca be referenced more easily.
The Step Doctype is a specialized type of section used to describe a sequence of actions.
Steps can also be listed inside a document by the use of the Steps Macro (as the container) and the Section Macro inside for each steps.
Modules
The Module Doctype's main and only purpose is to define content to be used for transclusion. Typically it has a section for the content to be transcluded. All other sections and all properties are used to categorize the module and add references to related information. The Module Doctype also provides a section that lists all documents that transclude content from the document instance.
Use the type property to categorize your modules. This may make it easier for authors to organize modules.
As with the Section Doctype, transclusions are easy with macros from the projectdoc Toolbox.
Topics and Tours
The Topic Doctype is used to document a topic. In contrast to the Section Doctype the topic is a document on its own. In contrast to the Module Doctype the topic's main purpose is not designed primarily for reuse. Use the Tour Doctype to organize topics in a single document.
Use the type property to categorize your topics. This may make it easier for readers to find information by browsing.
Resources
More information on modularization.
- Modular Documentation
- Use rich multi-excerpts (transclusion) for content reuse - even from page result lists. Replace parameters in excerpts. Include properties and sections from pages. Hide content dependent on roles and properties.
- Module
- A documentation module is a fragment which is usually transcluded by other documents. The lifetime of a module document is independent of the lifetimes of the documents that reference it.
- Section
- Sections of a document are typically part of a document. But the size of sections may vary. To support a team to write collaboratively on the documentation, a larger document may be subdivided into external section documents.
- Step
- Describes a single step of an activity. A step is a generic document that is associated with a document that describes a process. It may be a test log or a howto.
- Transclusion
- Tools to provide or consume content to support reuse.
- Content Reuse
- Provides support to reuse content from another projectdoc document. This includes the transclusion of blocks of content as well as short pieces of content.
- Modular Documents
- Tools (especially doctypes) that support the modularization of documentation.