In 2008, GDV DL faced the requirement to change the technological basis of their documentation because their Word-based solution had reached its limits. At the same time, GDV DL aimed to improve the overall quality of their documentation. Supported by parson, GDV DL migrated its documentation to FrameMaker/XML, completing this project in 2009.
Approach and methods
GDV DL chose FrameMaker/XML to use the potentials of XML regarding structuring and conversion into multiple output formats. We developed the XML solution in several steps:
- Requirements analysis (workshop)
- Specification of documentation structure and document type definition (DTD)
- Development of the FrameMaker structured application and design of layout templates according to corporate identity of GDV DL
- Pilot phase
- Migration of existing documentation (semi-automatic and manual)
- Training of future FrameMaker users
- Rollout of the new solution
- Development of a style guide for FrameMaker users
- Extension of the solution to meet new customer requirements
Special features of the XML solution
The FrameMaker/XML solution is based on DITA, but was adapted to the special requirements of GDV DL. Development of the solution followed these guidelines:
- Use a slim DTD: Rather than use all possible DITA elements, restrict the set of DITA elements to only the ones that are needed.
- Use a mixture of generic and semantic elements: GDV DL develops XML applications for insurance companies. This results in concrete requirements regarding the element definitions of the FrameMaker application. Specific semantic elements cover these requirements. In addition, generic elements like topics and sections enable the authors to structure the documentation more freely.
- Guide the authors: The design of the DTD prescribes a fixed sequence of elements for specific topic types. This restriction guides authors through structuring their content and results in a harmonized layout and structure.
- Ease of use: Complex processes, such as generating HTML output from the XML documentation, are started with a single menu command.
- Document the authoring guidelines: The style guide contains all documentation for the FrameMaker/XML application and guidelines for the authors.
Evolution to documentation-driven development
With help from parson communication, GDV DL extended the FrameMaker/XML application such that the documentation now provides direct control of development processes, servers, and user interfaces. XSLT scripts extract information from the documentation and import it into a database. These database records are used in the different development stages and form the basis for documentation-driven development:
- Specification phase: Software architects use FrameMaker to write preliminary documentation that is used to coordinate requirements and implementation with product managers and customers (insurance companies).
- Implementation phase: The database records that were created from the documentation are used to generate code templates for the software engineers, to automatically create classes, and to create validators that check ranges of values.
- Test phase: The database records are used to generate test case templates and test code.
- Operation of the web portal: The database records are used to generate Help pop-ups, to perform data validation in user forms, and to generate error messages.
Thus, the documentation takes a central role at GDV DL and acts as a data pool for all development phases. Due to the use of the XML data format, information is written only once and can be evaluated for different purposes. This reduces manual programming work, copy/paste errors, and duplicate implementation work in development and testing. Using this integrated approach, GDV DL was able reduce its efforts to develop new versions of their XML application for insurance companies.
- Session at tekom conference 2009 (German): Mehrfachnutzung einer DITA-basierten XML-Anwendung
- Session at tekom conference 2011 (German): Documentation-driven development