[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Improving semantic inlines for software documentation
Now that the DITA 2.0 proposal window is open, I’d like to suggest the following additions to the technical inlines of DITA.
In the process of creating software documentation using DITA, we are finding that several of the existing inlines are too generic and are being “overloaded”. Since I’m also on the DocBook TC, I think there are several elements that could be borrowed from DocBook (see http://tdg.docbook.org/tdg/5.1/docbook.html) to provide the appropriate semantics that we need:
Additionally, it is a bit challenging to mark up REST and Web Services APIs. I’d like to define some additional elements to describe:
It might be possible to address some of these requirements by adopting the systemitem element from DocBook:
This element has a class enumeration for further defining the type of item. Since we can’t use @class, perhaps @type or @role could be used for this purpose?
I have not drawn up a formal proposal, but am hoping to open the discussion on our SC towards development of a proposal for DITA 2.0 or a separate Tech Comm release.
Thanks and best regards,
Digital Aviation Learning & Development
OASIS DocBook TC, Publishers SC
OASIS DITA TC, Tech Comm SC, LW DITA SC, Learning Content SC
OASIS Augmented Reality in Information Products (ARIP) TC
Digital Aviation | Boeing
55 Inverness Drive East | Englewood, CO 80112 | www.jeppesen.com
This document contains only administrative, uncontrolled data under U.S. International Traffic in Arms Regulations.