Re: [dita] Action item completed - "Review Stan's Examples"

[Eliot Kimber <ekimber@contrext.com>]

As regards examples in the spec, I think it's important for examples to illustrate important cases, especially where specific cases are either not obvious or are edge cases. One of the challenges in the spec to date is that the examples are sometimes too simple for elements where the implications of certain cases are not necessarily obvious. This is especially the case where two or more elements might interact or might have different implications based on different attribute values or whatever, such as in maps and with keys. There aren't that many of these cases but when they do occur I think it's important to illustrate them in the spec as much as we can.

I think the examples in the XSLT 3 spec are a good model: they tend to illustrate all the key features or variants of a particular mechanism, complete enough to be realistic but not over detailed.

Of course, one challenge editorially is that we don't always realize that something is an edge case until we've got significant practical experience....

But I do agree that complexity just for the sake of illustration is not that useful--that's the role of instruction and commentary outside the spec.

Cheers,

Eliot

--
Eliot Kimber
http://contrext.com
 

ïOn 3/26/19, 6:08 PM, "Magliery Tom" <dita@lists.oasis-open.org on behalf of tom.magliery@justsystems.com> wrote:

    Robert, Scott, and I met Monday 25 March to discuss the series of code examples provided by Stan during the fadingly-recent DITAweb review of the element topics shared between DITA 2.0 and LwDITA.
    
    1. Our principal conclusion was that most of the examples would be best suited for some material produced by the Adoption TC.
    
    2. Current practices for examples in element-topics include:
    - Examples should not illustrate complexity that COULD be used; rather they should minimally illustrate the elements
    - Any example we use should illustrate either a common case or a best practice for DITA markup
    
    POSSIBLE TC DISCUSSION NEEDED: The above principles are potentially in conflict with a sentiment that implementers need as many diverse examples as they can get. This might be a discussion that needs to be had more extensively in the TC.
    
    3. Some specific comments that we captured while going through individual examples by Stan:
    
    <alt> - We do have an example of <alt> in the spec already. 
    
    <data> - It's nice that this is a real-world example, although it probably is longer than necessary. Also, there's a strong possibility that any good real-world example like this would probably end up (in reality) being marked up with a specialization of <data> anyway.
    
    <desc> - The list (and maybe the table) are problematic from a best-practice perspective: descriptions should preferably be short text that would be easily rendered by (for example) a screen reader.
    
    <map> - It would be better if this topic simply referred the reader to the keys section with its copious examples. However, the "bats" example in this topic does need to go.
    
    <note> - Not a best practice to have what is essentially a procedure inside a note.
    
    <ol> - Nesting is so basic and fundamental, there's probably no need to show a nested example here. 
    
    <prolog> - Another case of more complexity than would be appropriate for the spec itself. This would be good to have in an Adoption TC document.
    
    <section> - Something like this would actually be good for the <sectiondiv> topic. As a side note, as a best practice <section> elements should have IDs.
    
    <topicmeta> - We definitely want something more complex than what is in the current topic, but not as much as is in this example. What are the most common elements that people use in topicmeta? We thought navtitle, category (at least Scott uses), version and copyright (but only at the root level).
    
    <xref> - We do have a couple of examples that use keys/href already. Actually illustrating defining keys is outside the scope of the xref topic.
    
    mag