0

I have a requirement to include (precisely) a traceability mechanism of my requirements in the source documentation (in DITA). For example, the requirement IFU1234 indicates that we have to include the information about product disposal and recycling. I was thinking that I could highjack the 'draft-comment' tag to indicate my requirement number in the corresponding topic. I would then have the possibility to publish a PDF with these comments to show that I have covered all my reqs in my document. And then to publish a final PDF without the comments. Is it an acceptable use of the draft-comment element? Do you see another element that would be more appropriate for my use case? (We have no CMS, by the way.) Thanks,

annette.b
  • 3
  • 1

2 Answers2

0

I would not use <draft-comment> this way. What I would do is use <othermeta> with the name requirement and the content set to the requirement it satisfies. I'd then add processing to output the requirement in one version of the output and use @outputclass on the map to shut off the processing.

JulioV
  • 516
  • 2
  • 3
  • Did you forget to mark the example tags as code? The answer is a bit hard to read, and I suspect that's because you suggested the use of the othermeta element with the attributes name (set to "requirement") and content, is that right? But these elements do not show in your answer. That or the "data" element is what I would have suggested anyway. BTW, both of these can be found in the metadata element inside the prolog after the title of a topic. – Anders Mar 31 '14 at 16:47
  • Thanks Julio & Anders. Like Anders, I had to read your answer twice (I'm not a native English speaker) but I think I got it. I'll try the @outputclass (thought it could only be used for HTML output). – annette.b Apr 01 '14 at 12:23
0

I agree with Julio: metadata in the topic prolog is probably most appropriate, although you can use the data element in almost any context.

Note that for DITA 1.3 we are adding a new "release management" domain which provides explicit markup for use in map and topic prologs for capturing change history, including markup intended to identify the source of the change, such as an issue in an issue tracking system or a formal requirement. That sounds like what you're looking for.

If you want to be able to display the requirement information in some output in the same way that draft comment can be shown or hidden, that would be a pretty easy XSLT or PDF customization, e.g., to use the DRAFT runtime parameter to show the associated requirements in some appropriate way.

DrMacro
  • 656
  • 3
  • 4
  • The release management domain you describe seems to be exactly what I need (but I can't wait for the 1.3 release ;) ). Can you elaborate on the "pretty easy XSLT or PDF customization"? Customizations are new to me, I'm just setting up my first DITA project. – annette.b Apr 01 '14 at 12:25