- Created by Robert Reiner, last modified on 17. Nov 2021
projectdoc Toolbox
Properties are metadata that can be added to every projectdoc document. If you require a set of metadata for each instance of a document type, you should write your own doctype.
If you want to add metadata to a given document, add it to the table within the Document Properties Marker Macro at the top of the page. This is a simple name/value list with an additional column that contains row controls.
While a document type requires a certain set of properties to be present, authors may add any property they require. But keep in mind that it is difficult to remember properties that are not standard. Further more it is sometimes very difficult to sense the meaning of document properties that are not documented.
Common Properties
The following properties are useful for all document types and are therefore found in each template.
If a property is not valid for particular instance, you may add the 'hide' control to the last column. This will make the property invisible on the view of the documents (but still selectable on queries). If you do not want one of the properties on every document, you have to edit the template.
Please make sure not to remove the Name, Short Description or Sort Key property, since they are heavily used by projectdoc.
Short Description
The short description is a short paragraph of one to three sentences. It describes the content of the document and is a tool for the readers to determine, if they are interested to read the document or skip it.
Typically short descriptions are displayed on top of a document and in document lists. The short description is rendered together with the name and maybe more metadata from the document's properties. This supports readers with navigating the documentation.
For information on how to write expressive short descriptions, please have a look at Writing Short Descriptions.
Doctype
The doctype identifies the type of the document.
The property value is required to be text only. No macros are allowed. It is recommended to use only lower case letters and hyphens ('-').
Since 4.2
Since version 4.2 the doctype may be specified by the Doctype Parameter of the Document Properties Marker Macro.
There is a special document type called 'generic' that has this minimal set of properties and section. Usually the Documentation Architect defines a new document type, if a special kind of information is important and should be stored in its on structure. This will makes it easy for the team to keep these documents together and easily findable.
A document that is based on a doctype is called a document instance.
The doctype usually helps to select documents in queries and for the reader's orientation within the wiki.
For further information please refer to Document Types and Templates.
Name
Within a doctype the name of a document instance is recommended to be unique.
This uniqueness of a name within its doctype is not enforced. Documents may be added to a search by specifying a couple of spaces. But it is good practice to check this uniqueness within a space. Typically the title of a Wiki page is identical with the name. But there are exceptions from this rule, to make the documentation process easier.
Names must not contain parentheses or brackets of any kind.
Short Name
A short name is a unique name of the document. Many doctypes provide this common property.
The default value for the short name is the value of the Name property.
It is typically used for abbreviations. It may also specify a shorter title that is unique only in a given context.
A document my be called "Introduction to Wikis" while the short name is simply "Introduction".
Parent
The Parent property references the higher ranked document, typically of the same type as the child document. Usually the parent is a more general form of the child or is in some other ways a structuring instance.
In searches it sometimes proofs helpful to select documents with the same parent. It is also convenient to select documents by a more general type (such as give me all managers, where some managers are tagged as product owners, others as agile masters.
For some document types there is a natural name that fits better than the generic term 'Parent'. It is none-the-less beneficial to stay with the generic term. This way you may define queries having instances of different doctypes in the result set and display their parents in the parent column.
If the alternative name is so much more meaningful than the generic term 'Parent' you may hide the parent line in the document properties table and add an additional line that refers to the Parent property (or the other way round). Please make sure that the referencing property is in a later line than the referenced property. Use the Display Document Property Macro for referencing.
Types call this property typically Superordinate Type.
Audience
The audience is the group of readers the document defines as it target.
It is good practice to think about the goal of a document and its target audience first. The audience lists the roles the document targets at.
Subject
Use subjects to group your or your team's work together and to keep track which subjects are relevant for your project.
The property references document instances of type Subject.
Categories
Categories help to organize document instances in hierarchies.
The property references document instances of type category.
Tags
Tags allow to add arbitrary character sequences to group document instances, even of different document types. On searches tags allow to select specific instances.
Confluence already knows the concept of labels. Every label is also a tag. Tags are therefore like labels, but the character sequences added as a tag property are not visible at the label level. So you an author might add tags that are seldom used and is sure that these tags do not create a mess with public Confluence labels.
For further information, please refer to the Tagging Documents.
Flags
Flags allow to label documents, but without the need to provide documentation for them. While there is typically a Tag document for each property value element of the Tags property, the flags set to the Flags property do not need to have such a document.
Since 2.4.1
Available since projectdoc version 2.4.1.
Like the Tags' value, the Flags value will be take into account for meta-tagging the document.
For further information, please refer to the Tagging Documents.
Iteration
The Iteration property is a tool for the author to communicate the status of the document within its creation process. Readers get aware, how to interpret the information in the document.
The stages of the document development process are as follows:
Facade | The document has just been added with basic information. This is the skeleton of a document, ready to be referenced by other documents. |
|---|---|
Filled | Information has been searched and accumulated to reach the breadth of the document. Every idea is added and may or may not contribute to the final version of the document. This is like adding topics to a mind map to expand to the full potential of the document. |
Focused | Pruning and selecting relevant information and giving it more structure. This removes the ideas generated by the previous stage that do not fit nicely. They may be moved to other documents, merged with other sections of the same document or discarded. |
Finished | The document is ready to be used (but may be enhanced in future versions). |
Released | The document has been released for internal use. This will communicate to team members that the contents of the document and the implications on the team's process have been agreed on. |
Production | The document has been released for third party use. This makes it visible to team members that this document had been made available to others. |
Deprecated | The document has been used formerly, but is no longer supported. The end-of-live of its use has been started to be finally removed. |
Removed | The document has been removed and has no relevance for the project any longer. Removed documents are still found in the attic for future reference. The reasons for the removal should be added to the document's notes. |
If you start a new stage, change the value of the iteration property. So after you have created the document in the facade stage and you start to add additional information, set the stage to filled, until you decide you have aggregated enough. Then switch to focused to start the pruning process. If you are satisfied, tag the document as finished. If it is discussed by the team and accepted, move it to released. As soon as it is ready for delivery to third parties, tag it as production.
Once you decide the information is no longer valid in near future, signal this state by entering the deprecated state. If it is no longer valid, the document finally arrived in the end state removed.
Please notice that the first three states define a stage within the process the document is in, while the other states actually define a state the document has already achieved.
The first four stages are based on Use Cases: Requirements in Context (Daryl Kulak, Eamonn Guiney). The authors defines those stages to iteratively develop use cases. But we think those stages also help to create documents of any type.
The values for the iteration property are predefined by the Iteration Macro. If these iteration stages do not satisfy your requirements, you may add an iteration type doctype and reference these with a Name List Macro. The drawback of this approach is that the valid values are not listed in a dropdown, but you can define the stages you want to use.
Type
While Subject, Categories, and Tags are typically supported by all doctypes, the Type property refers to a document type specific type. Therefore there is typically a specific doctype type for that type (like the Role Type), while the documents for subjects, categories, and tags are shared by all doctypes.
Example Type on Role Doctype
There is a Role Type that allows to group roles by their type. There may be administrator roles and user roles. The type Administrator and the type User will not be shared with any other document types.
In contrast the Tag named Security may be used by all doctypes like Role, Topic, and Tour.
Do not be confused that there is a Tag Type to group tags. You can also tag documents of doctype Tag with the Tags property. The Type property of a tag document will point to a document of type Tag Type.
Sponsors
The sponsors property allow to specify which stakeholders take interest in creating and optionally maintaining a particular document.
This information is not relevant for every type of document. There is typically no need to specify which stakeholder is interested in the description of a user's role or a given category. But for topics, architecture decisions, or volumes (e.g. the arc42 Template) it helps to define the audience who is willing to provide resources.
Sort Key
The sort key is the primary tool for sorting documents displayed in a list or on a table. Usually the documents are sorted by name, but sometimes you want to impose a semantic order on the documents. For instance you have a collection of documents that introduce a reader into a given topic. The order of the documents is typically not the lexicographical order imposed by the name.
For further information please refer to Using Sort Keys.
Special Document Properties
List of properties valid on document level.
- Heading Number Start
- Controls the start number of the first heading on a page.
