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:

keycombo

ooclass

oointerface

envar

email (could
 be handled using xref, but an explicit element may still be more semantically useful)

uri (could
 be handled using xref, but an explicit element may still be more semantically useful)

productname (could be handled
 using keyword/abbreviated-form, but an explicit element may still be more semantically useful)

function

interfacename

methodname

returnvalue

type

package

parameter

property

Additionally, it is a bit challenging to mark up REST and Web Services APIs. I’d like to define some additional elements to describe:

service

endpoint

action

request

response

schema

auth

It might be possible to address some of these requirements by adopting
 the systemitem element from DocBook:

http://tdg.docbook.org/tdg/5.1/systemitem.html

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,

 

--Scott

 

Scott Hudson

Content Strategist

Digital Aviation Learning & Development 

 

Voting member:

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 

Jeppesen  | 
 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.