- Created by Robert Reiner, last modified on 08. Jul 2019
projectdoc Toolbox
Document types allow to guide authors producing information of a given type. They also help readers to find the information they are looking for quickly.
If you start a new document from scratch you have to think about a lot of things. Since you are adding a page to a wiki some of the decisions have already been made for you. Less freedom in this context is actually a good thing! Authors are experts with important information on their minds that needs to be turned into an externalized form to communicate with stakeholder and team members (including the author's future self).
Document types are page blueprints or templates with some extras. This includes homepages for doctypes and navigation to related document types.
Style already defined
A decision that is already made is the layout of the pages. Authors using a wiki typically do not need to bother with decision. There is one, sometimes more, templates for applying styles. Even if there are more than one, it is usually pretty clear which one to apply in a given situation.
Structure somewhat defined
Form follows function. So authors usually expect freedom on how the document is structured to pass the information effectively to the reader. But on the other hand the reader expects similar information to be presented similar. The reader should also not notice which author has actually written the document.
Therefore authors need tools to help them to align the new document with the existing documentation and the expectation of the readers seamlessly. A template can help. But we must not force the authors to follow the structure of the template mindlessly. The authors are still in charge to create the structure that delivers the information best, but the template is a guide to allow the authors to follow if no better solution is at hand.
Here are some structures a template defines that are usually best kept in sync with other documents.
- Properties of document types
- Names of properties
- Values of properties
- Order of properties
- Sections of document types
- Name of the sections
- Order of the sections
Usually these rules can be followed without any negative influences on the readability.The authors must not be forced to follow this structure. If a value of a property is not available and not important for comprehension, it must be left off. If a specific section is irrelevant or may not provide further understanding, it is important to leave it blank. Do not add any decoy text. If a paragraph, sentence, or even a single word does make the point clearer then drop it. In some cases it may also add to the understanding of a document, if sections are set in a different order or the content of several sections is written to one with an individual title.
Last but not least we are not writing to win the Pulitzer Prize for literary achievements. There are certain kinds of documents that are best consumed if they follow a rigid structure. Glossary items do not gain much appreciation if every entry presents its information in an arbitrary sequence. Meeting minutes are best parsed by readers if they follow a predefined structure. Every document that comes in numbers, that are aggregated in a number of views benefit the reader if they are similarly structured.
Content marginally defined
If the information in the document is not genuine, there is no entitlement for it to exist. So there is no constraint on the content with the exception of controlled vocabulary and probably a style guide. Again this is necessary to provide a consistent documentation for the reader with the least surprise according style, structure, and content.
Homepages
A homepage is a page that lists instances of a document type in a hierarchy. Besides the homepage there may be Confluence's index pages, which list all documents of that type in a flat list.
A homepage typically also provides links to more information on this doctype online and links to homepages of related doctypes.
Resources
More information on this feature.
- 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.
- Doctypes
- Doctypes define properties and sections for documents. They are essentially Confluence Blueprints that help to create pages in your wiki based on templates.
- Guided Writing & clutter-free Reading
- Do not clutter the view with non-information sections. Instead help authors writing identical structured content by the use of templates.
- Extensible by Spaces, Templates, and Macros
- Never be limited to the vendor's ideas: Create your own spaces, templates/blueprints/doctypes and macros based on components provided by the projectdoc Toolbox!
- Section Macro
- Renders a section, if the body is not empty. Supports authors to create content, clutter-free rendering without empty sections. Allows to transclude the content.
- Document Properties Marker Macro
- A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
- Doctype Maven Plugin
- Create doctype add-ons (OBRs) for the projectdoc Toolbox with Confluence Blueprints based on XML model descriptions easily!
More Features
List of features of the projectdoc Toolbox for Confluence.
- Deep Links
- With deep links properties from referenced properties can be accessed for rendering.
- Default Locations
- Document types have their default location within a documentation space. These default locations are called 'homepages'. If authors create new documents they can send them to these default locations within a given space. Delegate spaces expand this feature to find the default location in associated spaces.
- Delegate Document
- Delegating documents transclude sections and properties from a delegate document. Information may be overridden.
- Dynamic Linking
- A document template that uses query macros enables documents to dynamically render links to a set of related documents. If new documents are added to the system that meet the query criteria, links to these documents are automatically added to the querying document. This feature is also called dynamic lists or automatic linking.
- Enhanced Transclusion
- Transclude more than one self-contained snippet and mark transcluded information for authors. The projectdoc toolbox allows multi-transclusion from one document and even several documents.
- Extensible by Spaces, Templates, and Macros
- Never be limited to the vendor's ideas: Create your own spaces, templates/blueprints/doctypes and macros based on components provided by the projectdoc Toolbox!
- Guided Writing & clutter-free Reading
- Do not clutter the view with non-information sections. Instead help authors writing identical structured content by the use of templates.
- Information Systems Integration
- Via a free extension information from remote information systems may be rendered on a wiki page.
- Live Templates / Impersonator
- Use the structure from a page and render it in the current page's context.
- Remote Control
- The projectdoc Toolbox supports rendering a page controlled by request properties. This way a URL controls the contents of a page.
- Rich Custom Document Metadata
- Authors may add any metadata to a document and use these in their queries. The metadata may be displayed or hidden. This way authors can use metadata target at the reader and metadata used for authoring purpose.
- Single Sourcing
- The projectdoc Toolbox provides doctypes and macros to support teams to modularize their documentation.
- Space Hierarchies
- Organize spaces in hierachies with delegate and search spaces.
- Space Properties
- Properties may be set on space level and are inherited through space hierarchies.
- Variables
- Space and document properties may be used as variables with the projectdoc Toolbox.
- Web API
- To integrate projectdoc documents with remote systems the projectdoc Toolbox provides a REST API. This API is installed separately with a free extension add-on.
