Navigation through Lucene Queries

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.

Not tested for Data Center

The projectdoc Toolbox is not tested for data center environments.

Use of additional Database Tables

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!

One Site, one Locale

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.

Documentation work is challenging

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.

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

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

Document Property Rules

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.

Properties cached publicly

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.

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

Transclusions are slow

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.

Page Content Changes

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.

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