In the previous post, I described how we used DITA to automatically generate requirements documents for our projects, such as software requirements specifications (SRS), test cases, cost estimate, proposal for the customer, and so on.

Of course, DITA isn’t the only way to document requirements. Apart from a good old MS Word, there are various tools that let you store requirements in a database, integrate the database into your authoring tool, and even customize requirements for specific customers. However, there are some areas where you can fully benefit only when your content is semantically structured.

This post is the first post in a series in which I’m going to explain the unique benefits that only a structured format, like DITA, can provide when it comes to writing requirements documents.

So here comes Reason #1:

Reason #1: DITA Lets You Manipulate Content to Automatically Assemble Various Documents for Different Audiences

Let’s assume that we are documenting requirements for a word processor application. One of the features that the application should provide is an ability to save a document in PDF, HTML, and ePub formats.

The client that ordered to develop such an application probably expects that the requirement will be displayed in a document something like this:

reason1_formats4proposal

However, from the QA perspective, this is not a monolithic requirement. Each item in the list has to be tested and verified separately. If saving a document as PDF is successfully passed, it doesn’t necessarily mean that tests for the other two formats will be passed. Therefore, each of the formats should be defined as a separate requirement and managed separately (or maybe you will want to assign them to different developers).

Moreover, the last paragraph actually represents two requirements: “All links will work in all output formats” and “Links will be displayed with blue, underlined”. Each of these requirements should be tested and verified separately too.

So for a test cases document intended for the QA team, the big requirement should be decomposed into smaller chunks. They should be rendered in a tabular form that the QA team can fill out and use for testing. Also, for reference purposes, the QA team should be able to see the ID of each requirement. For example:

reason1_formats2testcases

Similarly, for a cost estimate document intended for internal use, each small requirement should be provided with a separate estimate so that the project manager can get a clear picture of how many hours each requirement will take to implement.

At the same time, when submitting the estimate to the customer, the project manager might want to provide a general estimate for the entire feature. From this perspective, the whole list of output formats as well as the statements about links and their formatting represent a single requirement.

This is when DITA comes in to the picture. DITA provides a semantic markup that can be applied on virtually any level. You can define an entire topic as a single requirement. In addition, you can markup smaller pieces of information within the requirement to make them separate requirements.

The following example shows how different pieces of content within the topic are marked up as requirements. As you can see, DITA attributes are used to provide management information about the requirement:

  • @props contains the estimate in hours and the team that will be working on the requirement
  • @product defines the project phase in which the requirement will be implemented

reason1_xml

(For the sake of simplicity, I’m using the standard DITA without any specialization.)

Once the content is marked up, there are various ways (I’m going to talk about them in upcoming posts) to automatically decompose various pieces of content and assemble them into different contexts. For example, you can retrieve the cost estimate from the attributes, display the cost estimate for each requirement, calculate the total estimate, and render this information in a tabular format.

reason1_detailedestimate

Alternatively, only the total cost of the requirements can be published if you want to provide a high level overview of the costs.

reason1_highlevelestimate

Similarly, we can retrieve the information about phases in which each high level requirement will be implemented and arrange the requirements in a table by project phases.

reason1_phases

So when your requirements are semantically marked up (and again, you can apply the markup on any level of granularity), the possibilities for how you can decompose, rearrange, and aggregate content are virtually endless. And by the way, all calculations in the examples above are done automatically!

In the next post, I’m going to talk about how you can benefit from the content reuse capabilities provided by DITA when writing requirements.

Leave a Reply

Your email address will not be published. Required fields are marked *