3 Responses to Structured Writing is Essential for Developer Docs

  1. Shane Taylor 2014/06/09 at 13:53 #

    Thanks for your post! One of the benefits of structured writing that so often gets overlooked is that predictable, consistent, clear semantic structures in your documentation increase the usability of your docs.
    Imagine a developer’s frustration if each topic in the API docs was structured differently based on the creative inclinations of the writer that day!

  2. Scott Abel 2014/06/09 at 21:15 #

    Brilliant commentary as usual. Thanks for sharing.

    Scott

  3. Roy MacLean 2014/06/10 at 12:51 #

    Excellent as always. The rhetorical structure here is effectively that of elements which would have ‘role’ IDs – for example, a paragraph with ID = ‘requires’. In addition there is the topic-reference model – here we have a Method referring to Datatypes, Events, States and Permissions, all of which could be marked up semantically. As well as generating links, this also allows us to perform checking – for example, not only that a Method topic has a ‘requires’ paragraph (which a DTD could enforce), but also that the paragraph contains a Permission reference, to an existing Permission topic (and so would become a valid link).

    It would be interesting to know how much of that Android documentation is generated automatically, and how much hand-authored.