OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-techcomm message

[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:

  • 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 

line

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.



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]