While documenting our code, we often need to add in code examples. With DITA, the simplest way to achieve this is by using a codeblock tag and pasting in the code you wish to refer to.
Although this may have been the quickest way to refer to code, it is far from being the most efficient. Problems arise when, for example; the code has been changed, and is no longer a valid example in the documentation; pasting in large sections of code leads to cluttered and unreadable documentation. We have often fell in to this trap…
DITA has a nice solution to this, the coderef tag! By using the coderef tag we could simply point to where the source code is, to have it appear in the documentation.
This meant that whenever a change was made in the code, the change would reflect in the documentation. This also meant that our DITA topics were a lot shorter and easier to read without the pasted-in code.
Here is an example of coderef in use.
<codeblock><coderef href="../src/taglets.java" /></codeblock>
The post Example code in DITA – The coderef appeared first on Heap Dump.