Tested for small Teams

The main target group of the projectdoc Toolbox are agile teams.

According to the macros you use on a page, projectdoc launches some automatic Lucene queries on each view access of that page.

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.

For trusted Environments ONLY!

The projectdoc Toolbox makes heavy use of transclusion. That is it transcludes content from on page to be displayed in another.

This may make it vulnerable for XSS attackers as is the case for the Confluence HTML macro.

Enabling these macros can make your Confluence site vulnerable to cross-site scripting attacks. You should only turn on these macros if you trust all your users not to attempt to exploit them. We strongly recommend leaving this macro disabled if you allow self-signed up or anonymous users to create content.

HTML macro

Therefore you must not install the add-on, if you cannot trust your users (with write access) completely! Alternatively you may choose to selectively deactivate those macros that you do not want to be used.

Not tested for Clustering

The projectdoc Toolbox is not tested for clustered environments!

Use of additional Database Tables

The projectdoc Toolbox caches document properties for quick access in the database. We use Active Objects for this.

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

Not in every Aspect easy-to-use

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

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

Migration

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.

Import of projectdoc Spaces

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

Complicated Reindexing

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

Cache Size

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

Properties cached publicly

The Document Properties Marker Macro puts all document properties into the cache. 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.

Documentation Evolving

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

Add-on Extensions

We are currently working on additional blueprints to extend the usability of the projectdoc Toolbox. These 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.

Transclusions are slow

To write modular content you may either link or transclude content. But keep in mind that transclusion 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.

Page Content Changes

Due to the nature of automatic 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 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 list macros. There are 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.

Document Property Rules

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

• 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).
• 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).
• No transitive closure, only direct references are (currently) recalculated on property value change (this is usually no problem as long as you do not reference a value that by itself references a value). This is due to performance considerations.

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.

Transclusion Rules

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.

Search Query Syntax

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.

API not finalized

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.

No Paging

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.