Flexible documentation with DITA
Standard software is delivered with standard documentation. Software is often customized for specific customer use. This results in the task of extending the standard documentation to include the customer-specific functions. Projectdocumentation documentation is created from the standard .
How do you ensure that standard documentation and project documentation still run synchronously even when updates and further development of the standard functions take place, and that you do not have to maintain two documentation statuses in parallel?
Rethinking: Documentation as 'source code' that is developed agilely like software
Let us consider standard software, including documentation, as a development project in its own right.
Then the sources and files of our documentation are the source code, analogous to the source code of our software. Our documentation is like software in this view.
It is composed of documentation modules of reusable basic resources. Documentation is developed like software. Ideally, we do this in parallel with the software development cycle.
Changing this mindset means changing the way we write, or rather develop, documentation.
In the scenario we outline here, documentation creation must adapt to, or at least approximate, software development processes.
For documentation creation to be meaningfully integrated into software development, documentation creation tools must not rely on proprietary data formats (such as unstructured FrameMaker, InDesign, Word).
These formats are unsuitable because they are not machine readable at all times without complex converters. For our scenario, however, this is exactly what is needed.
This leads us to XML and thus to the now established DITA standard. Documentation creation based on DITA can perform the task described at the outset of 'developing' standard documentation and project-specific documentation in parallel with the software development process.
An agile mindset and a tool landscape that relies on established standards are a good basis for bringing technical writing and development teams together. developers are integrated into the documentation development process as content providers. More: External designers, developers and consultants can also be integrated into the documentation process. We can provide them with content for project-specific documentation based on a modularized and reusable foundation.
Let's take a look at the concepts with which the DITA can support us in agile documentation.
We explore the question: How can we use tools that are already established in software development for editorial work?
Using Reuse Mechanisms in the DITA Flexible Documentation Creation
Reuse is one of the strong basic concepts of DITA. And it is precisely these very mature and sophisticated concepts that help us to implement project-specific software documentation.
Let's start with the simplest mechanism keyref.
keydef and keyref are nothing more than variable values that we store in our documentation (keydef) and reference in the appropriate places (keyref).
Nothing new, because we know the use of this mechanism from Word, FrameMaker and other editors and systems.
However, in DITA these variables are defined in separate and, if necessary, multiple files(key maps). Simply by changing the underlying scope, the key space, the contents of the documentation can be changed. The files can be exchanged for a publication of a specific documentation variant or shown or hidden via variant management as part of profiling.
The conref mechanism also quickly becomes apparent.
Content from a resource pool can be referenced and integrated into the publication.
Adobe FrameMaker, for example, implements a similar mechanism in the unstructured variant using text insets.
A text inset is a fragment that is stored as a standalone file, and then included in the content as a referenced copy.
If you change this fragment, all content in which this fragment is referenced or embedded will change.
DITA goes one step further here: Addressing with the help of IDs in the resource topic can also be used to include only a certain part, starting with a defined ID and ending with another ID.
A single topic can thus contain multiple resources that are included in different places.
A practical example of this is the central definition of security notices and their inclusion at the relevant points in the document/topic context.
The use of conkeyref, on the other hand, is a bit more complex.
This mechanism combines the two approaches keyref and conref.
In the DITA, a resource file is defined as a variable and the ID is referenced in this topic along with the key.
This means that by exchanging a reference to reusable resources, other content can be brought in that is needed for a project-specific variant of the documentation.
Here is a small code example to illustrate:
<keydef keys="project.screenshots" href="screenshots.dita" format="dita"/><keydef keys="project.screenshots" href="screenshots-project-A.dita" format="dita"/>In the basic resources we refer to the screenshots.dita resource pool, which contains our screenshots and possibly a descriptive part about the respective dialogs.
Since we are in the base pool, these can also be placeholder graphics. For the project-specific documentation we now only exchange the reference to the resource pool for screenshots(screenshots-project-A.dita).
Without a single change in the basic resources, we get the right screenshots for the given documentation variant.
The conref push is then the upper end of the possibilities.
conref push allows us to perform Content Injection. This refers to adding (injecting) content into base documentation when using base resources in a specific project context.
For this purpose, a 'reuse' or better 'injection topic' is created, in which content is referenced via conref from the base documentation. The conaction attribute provides us with three ways to inject content into the documentation. First, we can use pushbefore and pushafter to hook content before the referenced content or after the referenced content from outside. As a third option, we can use pushreplace to completely replace a content with the project-specific content.
The prerequisite for this to work in more complex projects and to be understood as intuitively as possible is the definition and clean assignment and naming of IDs for the reusable and extended content.
The following sections outline two use cases for the Reuse mechanisms. These are interface texts and screenshots as well as variant management with the help of profiling.
We then highlight the advantages and opportunities that arise from the changed and, as we see it, 'modern' approach to documentation development in parallel with software development.
This involves the management of documentation content, publication planning and the integration of external parties into the documentation process.
First use case: Interface texts and screenshots
Software documentation often uses texts that appear in software interfaces to establish an appropriate relationship between documentation and software.
Dealing with these texts is not always easy, especially if the documentation is to be translated into several languages.
To set up this process cleanly, an interface between development and technical editing is required.
If a software is state-of-the-art, the interface texts are maintained in external resource files, translated and integrated into the software depending on the language.
So it makes sense to generate Key-Maps from these resource files in the build process of the software. The appropriate content in the documentation can then be referenced from these key maps. The documentation thus always remains up-to-date and correct.
Some software builds even go so far as to generate screenshots in an automated and partly language-dependent as well as project-specific manner.
We can also use this mechanism in documentation creation to create language and project specific topics that reference these screenshots (see source code example above). Using the conkeyref, we can automatically include the screenshots in our various project documentation.
Second use case: Variant Management
DITA provides Profiling to exclude certain content during output.
This generates customer-specific documentation. This happens via attributes. The profiling mechanisms are controlled during publication via a so-called DITA-VAL.
Profiling markup is possible in almost all DITA. If necessary, they can also be expanded by specialization to meet specific needs.
If you look at this feature in isolation, it already helps to generate project-specific documentation.
In combination with the described Reuse mechanisms, the possibilities increase even further. This is because reuse topics or key maps can also be included or excluded accordingly via the profiling mechanism. A maximum degree of flexibility is achieved.
Integration of documentation into the software development process: Content management
In many software projects, version control systems (VCS) are used, such as GIT, Bitbucket or (still somewhat more classic) SVN.
VCS thus offer a flexible, release-oriented management option for source code.
In our new view, technical documentation is just that, source code.
That is why we need source code management. And one that is aligned with the release cycles of our software. A management that also allows us to integrate our documentation with the different development levels of the software.
If we proceed in this way, we will have paralleled our documentation releases to the software simply by managing them in the appropriate development states.
This is particularly helpful for our project documentation, as customer-specific adaptations naturally lag behind the latest software base release. Project documentation must therefore also be able to use basic resources from older software releases.
This is made possible by the use of VCS and the assignment of certain documentation statuses to certain software release statuses.
Planning of the documentation publication: daily/nightly builds
Because we think of documentation as source code, we can also think of the publishing process like a software build process. In many scenarios, software builds run automatically. They consider testing and validation especially in Test-Driven-Development.
The DITA Open Toolkit is a free tool available as open source.
This allows us to integrate the generation of the various documentation variants, including project-specific output, into the software build process in an automated manner. We can thus add the document generation to the step that provides us with the updated software texts and screenshots.
In this way, we have documentation available that is up-to-date and appropriate to the software status, related to different releases and even, if necessary, for different intermediate statuses of the software and the associated documentation.
The documentation build process can validate the content in intermediate steps. This can be done structurally as well as with respect to the referenced variables and other Reuse components.
The result is a report about detected errors or problems in the database, which can be reworked on a daily basis if necessary (before the next release is just around the corner).
Involving external parties in the creation of documentation
After we have created and released the basic resources, we deliver them to third parties, such as consultants or designers. Ideally, we provide this delivery with creation templates. Based on the templates, external parties have the possibility to create the project documentation, with the requirement not to change the basic resources.
In the simplest case, they adjust the project-specific variables (keyref) in the template files and add project-specific details in the appendix, which initially have nothing to do with the software itself.
When adapting the software, i.e. during configuration or, if necessary, through own program-technical extensions, the contents are now supplemented or replaced by means of the extended reuse mechanisms.
Conclusion: Documentation that fits
Since software is inherently structured, ways can also be found in specific cases to extract information directly from the software and integrate it into the documentation.
The simplest example here is the interface texts of the software.
This approach is admittedly complex and requires a corresponding learning curve, especially when third parties come into play.
However, the advantages of this approach are obvious: One uses the existing standard documentation and delivers customized documentation.
This is possible by changing or replacing exactly those contents that deviate customer-specifically. At the next software update the relations ( e.g. conref) are still present.
The documentation updates itself in the standard area. In addition, it is not necessary to recreate the entire documentation, but only the parts that have actually changed from one release to the next.
And what about companies that do not accept xml data as delivery, but expect Word?
This target group can also be supported. A Word is just another form of content delivery. It can be easily generated from existing DITA documentation resources.
The infrastructure described here represents a documentation solution based on established standards and mostly already existing processes and tools. This solution is integrated into the software development process. Is there anything wrong with letting your customers, consultants, developers and designers access this infrastructure as a special service and integrating it into your process and thus binding them to your company?
What has been described here for software documentation can easily be applied to operating instructions, quotations, contracts and other types of documentation.
Our offer: Conversion of your Word, InDesign, FrameMaker to DITA
We support you on your way to documentation that is based on standards and thus opens up many automation possibilities.
