The list of features of the projectdoc Toolbox on a single page.
Document Types
Rich Custom Document Metadata
The metadata for a document is specified by the use of the Document Properties Marker Macro. Each piece of metadata is called a document property, consisting of a name, a value, and document property controls.
The metadata can be used by query macros like the Display Table Macro or the Transclude Documents Macro to select on projectdoc Documents.
Properties can also be transcluded by the use of the for instance by the Display Document Property Macro and Display Document Properties Macro.
Enhanced Transclusion
The projectdoc Toolbox provides macros to transclude elements from a document into another document. These elements may be properties or sections / marked content. There is no limitation on the number of properties and sections to transclude.
Dynamic Linking
Dynamic linking allows to render links dependent on the context at request time. Request time is the time when a page is rendered for a reader in the web browser. Dynamic Linking refers to a list or table of links, which is called Dynamic List, or a single link, which is called a Dynamic Link.
Dynamic Lists & Tables
A dynamic list may be rendered as a list or as a table. Sometimes it is also called and automatic list, because the links are rendered dynamically and automatic at request time.
Each list item or table row represents information from one document that is member of the query result set. A query contains constraints to match all documents of a given document type and a couple of tags. When a user browses to a page with a dynamic list, the system executes the query and shows all pages that match that query at request time.
In the following screenshot you see a dynamic list, rendered in form of a table.
You specify queries like this:
SELECT PropertyOne, PropertyTwo, PropertyFour
WHERE PropertyOne = "Some String" AND
(PropertyTwo = "Another String" OR PropertyFive = "Something")
SORT BY PropertyOne, PropertyThree
Note that this is pseudo syntax. The values for SELECT, WHERE and SORT BY are passed to the macros as parameters.
Dynamic lists is supported with
- Display List Macro
- Lists references to projectdoc documents in a list. List contain names and optional short descriptions.
- Display List Template Macro
- Lists references to projectdoc documents in a list. List items are defined by templates referencing properties.
- Display Table Macro
- Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
- Index Card Macro
- Renders transcluded content fetched from documents of a result set.
- Index Entries Table Macro
- Renders a table of index entries.
- Transclude Documents Macro
- Renders transcluded content fetched from documents of a result set.
Dynamic Link
You may also want to render a single link to a document that may or may not exist. If it exists you have control over the rendering of the link. It may for instance be plain text or the label is not rendered at al. Use the Dynamic Document Link Macro and configure the rendering of the link with the Link Rendering Control parameter.
Guided Writing & clutter-free Reading
A template typically puts a demand on the author: fill out everything! Or remove what you did not fill out now! Neither is appreciated. The authors have a set of information in their minds they want to contribute. Maybe the document is created collaboratively. Certainly it is created iteratively. This especially applies to project documentation, where the team writes for the team. In this case the documentation is typically never finished. Rather the documents are in different states of the iteration cycle. Yet the information provided is already relevant for other team members. Do we want our readers to be confronted with empty sections only attached to a decoy title? Do we add value by some decoy text like "TBD"? On the other hand, if the boiler plate parts are removed, we have no access to them when we or other teammates need it.
The result of this feature is that an author is provided with support adding relevant information at the expected positions and also has guidance according to what information may be relevant for my audience for this kind of document. On the other hand the reader is only seeing section with actual content. The same is true for properties.
- Properties are only rendered, if they provide a non-blank value
- Sections are only rendered, if the body has actually content
As a screenshot this feature looks like this:
In edit mode the authors have access to the structure that is defined by the template. The authors decide which information they need to add to the document and stores it at the defined locations. They may add any number of additional properties or sections. Any properties or sections that are not yet (or never relevant), are left empty. Once the document is saved, only those properties and sections are presented to the reader that actually contain relevant information. On the left side there is the view of an editor with sections that have content or have no content. On the right side you see what reader's see in view mode. Sections with no content are not rendered.
The Section Macro allows to define possible information for a given doctype at a defined position within the document. Typically this section contains text supporting the author to know which information is expected by the reader for each section. The Section Macro also allows to link to more information by the use of the help button (marked with the image of a question mark 
).
Space Properties
Space Hierarchies
According to the projectdoc Toolbox for Confluence spaces may be related in two ways:
The Delegate Space feature is used to define hierarchies. A space property defined in a delagate space is inherited to the delegating space. Also homepages for doctypes, not defined in the delegating space will be inherited from the next delegate space.
A space attached to the Search Space of a space enables macros selecting documents (for instance the Display Table Macro) to automatically include documents from the search space.
Default Locations
Homepages to store Documents
Each template is defined by a doctype that defines the basic structure of every document instance of this type. The structure is a compilation of properties and sections.
In projects documents of the same type tend to be accessed together. Think of documents that describe roles or personas. Or design decisions, meeting minutes, the documentation of aspects of a software architecture. projectdoc defines a default location called homepage for each (with some exceptions that should not bother us here) document type. The homepages are similar to index pages you may already know. There is only a slight difference. While index pages collect every page that has a certain label on it, the documents on the homepage are the most important documents of that type. There may be more documents that are children of these root types. Think of roles! There may be a role document that describes the most generic user of a system. Subdocuments of the User document may be specialized users, like Power User or Admin User. The homepage only has a reference to the User document and allows the reader to drill deeper into the hierarchy step by step. If the user needs an alphanumeric listing of all roles, the index page is still around. But the documents are typically not stored on the index page, but as pages of the homepage or as a descendent of one of the root documents of their type.
If you create a space, all homepages are created by default. The space homepage lists references to the homepages (either directly or indirectly).
Here is an example from a space created by a projectdoc space blueprint.
The 'Topics' link on the space homepage refers to the homepage of the Topic doctype. There is one document instance on this homepage called 'Installation Howto'. On the homepage there are more links to homepages of doctypes (for instance Tours, FAQs, and Glossary). If a team defines a basic structure for their spaces of a given type, new group members, who have worked with other teams on other projects, will have an easier time to get familiar with the domain of a new project. They still have to learn the new domain, but they are already familiar with the structure of the documentation for this domain.
Default Target to store Documents
Each page wizard for a doctype that supports a homepage, there is a flag to store the document either as a child to the current page (default) or to send it to the homepage for this type.
The screenshot shows the creation of a document for a role named 'User'. The author decided to store the document to the homepage of the 'Role' doctype instead of saving it as a child to the current page. The current page is the page the author viewed when she decided to create a new page by starting the wizard.
Delegate Spaces and Homepages
Some documents are relevant to more than one space. If you have a large project with multiple large components you may want to have a space for each component you describe. Each component may share the same roles and topic types. So there is no need to have them copied around spaces. Instead have them stored in a collaboratively used delegate space.
There may be more than one delegate space. Delegates spaces are specified in an ordered list.
Whenever an author sends a document to its doctype homepage, the document is stored to the immediate homespace page found in the delegate space hierarchy. Assume for instance that the current space has a delegate space with a homepage for roles, but has itself no such homepage. If a document of type 'Role' is sent to its homepage, then it will be stored on the role's homepage on the delegate space.
Single Sourcing
Single sourcing is an approach to reuse content by making sure that each piece of information has only one authoritative location.
There are a couple of tools in the projectdoc Toolbox to support single sourcing:
- The Section Macro and the Content Marker Macro allow to define pieces of information on a projectdoc Document. Using the Transclusion Macro or the Transclude Documents Macro the content, defined in a single location, can be rendered on any other page.
- Also Dynamic Linking allows to automatically pick sections from other documents.
- The Module and Module Type doctypes allow to specify a piece of information on a separate document. By defining types of modules, the individual pieces may be organized to be found by browsing. Additionally the documents may provide additional metadata used to filter or be provided as helpful information for other authors.
Delegate Document
Live Templates / Impersonator
The Impersonator is closely related to transclusion. But instead of transcluding content from another page, the impersonator transcludes only the unrendered content and renders it in its own context. The transcluded, unrendered content is used as a template that is rendered at request time. Therefore it is called live template.
For more information and an example of usage, read the tip Impersonator - using Live Templates!
Deep Links
Web API
The Web API allows to access projectdoc documents remotely via REST.
Use the REST API Browser of Confluence to start using the REST API provided by projectdoc.
The browser is accessible via plugins/servlet/restbrowser. For more information please refer to Using the REST API Browser.
The Web API also supports users to create bookmarklets to automate recurring tasks.
