Confluence is a great team collaboration tool. The projectdoc Toolbox is an add-on for Confluence. The toolbox supplements the standard tooling with enhanced features like transclusion and dynamic linking. These features make it much easier to create modular, single-sourced documentation and create a rich navigation within your wiki.

The main target audience of the projectdoc Toolbox are agile development teams. It supports any team that requires to create and maintain documentation collaboratively.

This page lists topics to consider to help interested parties to evaluate and get started with the projectdoc Toolbox.

If you have any questions regarding the projectdoc Toolbox, please do not hesitate to get in touch!

According to the macros you use on a page, projectdoc launches Lucene queries on each view access of that page. These queries locate matching documents to render links for navigation.

In case you plan to install the add-on on a server with a large user base or heavy load, please make sure to check your performance requirements thoroughly in advance.

The projectdoc Toolbox is not tested for data center environments.

The projectdoc Toolbox caches document properties for quick access in the database. We use Active Objects, a recommended feature provided by Confluence, for this.

Please check if this is allowed by your installation guidelines in advance!

Generation of documents requires a locale so that the projectdoc Toolbox knows the language to use to generate property names and section titles. The selection of the locale is defined by the site locale.

To change this there must be the notion of a locale per space or even page. A macro can at any time render text dependent on the locale of the current user. But on page creation the generated text need to follow the locale of the site. If the locale of the user would determine the language of the generated page, a space would have documents for different languages.

Currently it is not supported to have the locale be determined by a space or page configuration (see Controlling Locale/Language for Space and Page Blueprints in Confluence).

A possible workaround: The templates a blueprint is based on may be translated at space level. This way the template of a blueprint for the site locale "English" could be translated in a space to e.g. "German" (see Blueprints Cannot Be Configured to Use Non-English Languages).

Please refer to Localization for more information on this topic.

The main target group of the projectdoc Toolbox are software developers that seek for tools to make documentation tasks more easy and fun.

Despite our constant work on making the projectdoc Toolbox easy to use, there are some features that may be too complicated for non-programming audiences. It may be advisable that your documentation architects have a thorough look at the add-on's features to check, if these will work with their authors.

Some of the features that might cause problems with your users are listed as need-to-know below.

Currently we do not provide any migration tools, in case you need to move from one version to another.

This issue is based on the fact, that pages that have been created with a blueprint do not get adjusted to changes to that blueprint. So this problem is not specific to the projectdoc Toolbox.

If any incompatible changes have to be applied in the future, it is likely that you have to rely on your set of tools to update your pages accordingly. That is not that we do not take compatibility issues into account and try to provide a solution for our customers. But currently we cannot guarantee easy migration paths.

The import of spaces that use macros from the projectdoc Toolbox is even slower than what you experience with your Confluence spaces.

This is because the projectdoc Toolbox has to do some extra calculations for each imported projectdoc document.

In case you have to reindex your projectdoc space, there is only a developer tool to support this task. The tool is quite crude and not very responsive (that is it starts and comes back when it has finished without any advancement information).

The projectdoc Toolbox Document Cache is set to 1.000 entries, and has to be adopted to your installation needs (usually at least 10.000 entries ^2|3).

There are some rules to follow, when working with document properties:

• Do not reference properties in documents with different permissions.
• Do not add sensitive information as property values (they are written to the Lucene index by default).
• Do not have a dynamic value for a property.
• It is recommended to only reference properties of the same document, if they are already defined (i.e. are defined in a row above in the document properties table).

These rules may be too complicated for some audiences that are not used to programming. We try to make this more convenient in the future, but for now you should discuss these rules with your team.

The Document Properties Marker Macro puts all document properties into the cache and into the Lucene index. Therefore these properties must not contain sensitive information!

If a page is accessible for a user, all properties of that page will also be accessible for that user - even if the property is set to hide.

We are still adding information to our documentation. The documentation is not  - and probably will never be - complete.

We are continuously working on additional blueprints to extend the usability of the projectdoc Toolbox. These doctype add-ons will make it much easier to get started. Without these add-ons you'll have to define all your templates by yourself. While this is an approach many teams may chose to take anyway, it may slow down the project start of others.

Please refer to Doctypes to see what is already supported and what is in the queue to be released.

Note that all doctype add-ons are provided for free on the Atlassian Marketplace and are hosted on Bitbucket.

To write modular content you may either link or transclude content. But keep in mind that heavily use of transclusions is slow. Check your performance requirements and your server resources and design your documentation strategy accordingly.

From version 1.9 on there is a global cache to store transclusion fragments. Please refer to Fragments Cache for Transclusions for details.

Due to the nature of dynamic lists (for instance the Display Table Macro), the content of a page displayed to a reader will change without the page having been edited.

This is similar to the behavior of macros provided by Confluence that show pages with a specific label. If an additional page is tagged with a particular label, the list on the page with the macro changes. This is true for all our dynamic list macros. The projectdoc Toolbox provides no tools to permanently freeze the content of these lists.

We recommend to export these pages to PDF or other media, if you require a snapshot for later reference. Alternatively you may use the Tour Macro to specify the elements of a list explicitly.

Do not transclude content in a cycle!

This rule applies to the Transclusion Macro as well as to all display property macros (e.g. Display Document Property Macro).

Since version 1.9 the projectdoc Toolbox tracks recursions and will render an error message if a transclusion cycle is detected.

The syntax of the search queries is based on the Lucene syntax and therefore is quite complicated. It may be frustrating to formulate complex queries for users that are not used to programming.

We will change the Java API without notice. It will probably take the next major release, until we finalize the API and add documentation to help macro developers.

Please do not depend on our API! And if you do so, do not complain about regular and incompatible changes in our releases.

We recommend to get in touch, so that we can help you on any updates.

The result lists are designed to be used for hit counts of 50 or less. Therefore we currently do not support paging for the query macros.