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