DITA Technical Communication SC

 View Only
Back to discussions
Expand all | Collapse all

Improving semantic inlines for software documentation

  • 1.  Improving semantic inlines for software documentation

    Posted 02-09-2017 17:56





    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.






Related Content