OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] DITA users want more (and better) examples

I had a look through the notes made from the various DITA Listening Sessions in the past and found this nice summary of user comments relating to relating to the DITA specification in general:

San Jose DITA spec Would like a searchable version of the spec. 
Cambridge DITA spec The spec needs more complex examples, ones that do not dwell on obvious/easy stuff.
Denver DITA spec Not seeing top-notch technical writing in the spec.
Denver DITA spec Must develop internal DITA specs to compensate for lack of clarity and good examples in the spec.
Littleton DITA spec The examples are not realistic, too simplistic for teams deploying features with complex content.
Littleton DITA spec Need examples and use cases directed toward multiple audiences (technical, managerial, financial).
San Jose DITA spec More use cases and examples would be helpful.
San Jose DITA spec Need more holistic examples. 
San Jose DITA spec Spec needs to be more accessible, too difficult to drill down and to get needed information.
San Jose DITA spec Need better examples in the spec. 

As you can see, the most common refrain from the DITA users we have spoken to is that they are seeking better examples within the specification (and it is clear that people have been turning to the specification for this type of information).  

There were also comments across a few of the DITA Listening Sessions that some of the code examples that are out there (such as Thunderbird, oXygen's docs and Eliot's DITA 4 Publishers examples), were very useful as a supplementary source. So people want better, more realistic, examples in the specification, while knowing that there are other resources that are also available.   

I have passed along your more specific questions to the people who are running the next DITA Listening Session tomorrow, so we ought to have some answers prior to the next meeting.




Keith Schengili-Roberts
Market Researcher and DITA Evangelist
825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1
tel  + 1 514 279-4942  /  toll free + 1 877 279-4942 

From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com>
Sent: September 18, 2018 9:50:17 AM
Subject: [dita] DITA users want more (and better) examples

This is what the DITA Adoption TC has heard at listening sessions.

I want to poke at this. Do we have any idea what DITA users mean when they say "We want more and better examples"? Before we try and jump to a solution, I think it would be helpful to define the problem.

I think the example issue might be multi-faceted and encompass a very wide range of of items:

  1. Some folks might want examples in the spec that reflect real world usage, not bats or puffins or garages.
  2. Some folks might want more examples to cover edge cases.
  3. Some folks might want more examples to illustrate what is handled by attributes on DITA elements.
  4. Some folks might want tutorials.
  5. Some folks might want access to more sets of sample files. (Not a DITA TC concern)

Let's also not forget that many users do not look at the spec at all ...


Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
+1 919 622-1501; kriseberlein (skype)

--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]