Hi,
I've reviewed the article; this will be a very helpful item for many people. I do have a bunch of comments, so of them substantive. I'm attaching a commented PDF version of of the article; if it doesn't get past OASIS's filteres, let me know and I'll post it in the 'documents' section of the adoption TC site.
But I also have some general comments:
1. Structure: the entire article seems to have been generated from a single <dita> topic with sub-topics, or at least that's the only thing that explains the current structure. I'd recommend the following, where the large type indicates the beginning of a major section, followed by it's child topics
:
Why Short Descriptions are a Good Idea 7
Why Use Short Descriptions? 7
Short Descriptions Make Content "Easier" for Readers 7
Telling Readers Why they Should Read Your Topic 7
Short Descriptions as Preview Links in Online Documents 8
Good Short Descriptions = Better Search Engine Results for Online Documents 8
Short Descriptions Can Help Content Creators Find Content for Reuse 8
Short Description Best Practices 9
Use Short Descriptions Consistently 9
How to Write Short Descriptions for Task Topics 9
How to Write Short Descriptions for Concept Topics 9
How to Write Short Descriptions for Reference Topics 10
How to Write Short Descriptions for Glossary Topics 10
How to Write Short Descriptions for Troubleshooting Topics 10
How to Write Short Descriptions for Maps 11
Abstract and its Relation to Short Description(s) 11
Do Not Use Cross-references in Your Short Descriptions 12
Converted topics 12
Conclusion 12
2. We need to inform readers of where topic shortdesc content is displayed; for example, it does not typically get displayed within the body of a topic in PDF or online output; it shows up as link targets, or pointers to child topics, or hover help, etc. I think a big reason folks are confused about how to use shortdesc is that they don't understand whether and/or how it will show up in their various outputs. The article could use a bunch of visual examples to illustrate where it does, and does not, show up.
3. I found the 'best practices' section on maps to be confusing; the explanation needs to be clearer, and again, some graphic examples of usage with corresponding PDF and [formatted] HTML output (with hoverhelp as appropriate) would be invaluable here.
Thanks again, Keith and Joe, for taking this on.
Nancy