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 automatic 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 is dedicated to list limitations 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!

The projectdoc Toolbox is not tested for clustered 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.

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 pagedocument.

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.

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

We are currently 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 transclusion 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 automatic 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 behaviour 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 automatic dynamic list macros. There are 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.

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 with us, 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.