projectdoc Toolbox

References are links to information that back up the information in this document. Resources refer to additional information to the topic discussed in the document and related information.

Level of Experience


References are used to back-up the information provided in a document.

Use references if you want to provide a list of citation targets. Often this preciseness is not that important in project documentation.


Resources on the other hand suggest further readings. Information that is related to that given in the document and may also be interesting to the reader.


If you are unsure if you need both references and resources, skip references.

Rendering Links to Documents

Typically you add one to three sentences describing the referenced resource, similar to a Short Description. If the resources are found in your project documentation, you may use the Display Table Macro to list the tagged resources. For single entries you may use the Display Document Properties Macro with a template like

$[Name] - ${Short Description}

Another approach is to use the Tour Macro to render additional properties as columns. As long as there are only two columns, the tour can be rendered as a definition list instead of a table.