Re: Where do YOU go for high-quality information about DITA? #resources

Chris Papademetrious

OMG Chris, this this this this! Your post is right on the money and describes my own experience perfectly. Thanks for taking the time to write it up.

[copy and paste his response as mine here]

 - Chris

P.S. My wiki suggestion was so I could make this hard-won "info-in-the-middle" knowledge available to others before moving on to the next urgent task.

On Mon, Jan 13, 2020 at 6:25 AM despopoulos_chriss via Groups.Io <> wrote:
If I need information about a specific element, I go to the spec.  For information about how DITA works in my current tool, I go to the tool docs.  For XSLT information I go to and stackoverflow.  To use the OT, I go to the OT docs (thanks guys!), but the authoring tool I use hides the OT from me, so its been a while.  These are all good sources for using the specific tools at my disposal (assuming DITA is itself a tool).  But there's a level of information that is hard to put together...  How these tools all work together to make a publishing chain. Hot to implement best practices, and why.

There's lots of documentation about what DITA is, how to think about using it, and various guidelines for authors.  The specs describe what a DITA implementation must support.  What's missing is documentation in the middle.  There are a few blogs and even maybe books that bring the specs a little bit closer to the human scale, but not much closer in my experience.  Unless you want to devote your career to learning this stuff (basically, implementing it yourself to learn what works and what doesn't), it seems there isn't much help.  I think this is for two reasons, which center on the level of expertise you need to get to know this stuff:

Cynical Reason:  After investing in this knowledge, you want to make money, not friends (ok, pretty harsh...  bear with me).  One obvious direction to take this knowledge is into a product that codifies the knowledge.  This actually provides a service in that it shields the average user from needing to know.  The hope is that users will rely on your product, and let you take care of the knowledge.  You have little motivation to tell all because it encourages competition.  And an effort in sharing knowledge takes away from resources you could pour into R&D.  Which brings up the noble reason...

Noble Reason: Time spent sharing knowledge is time not spent applying your hard-won knowledge or acquiring new knowledge.  Even so, some noble people have tried to lay out their discoveries.  Sadly, the information I have found at this level assumes a knowledge of the spec that is so intimate that you probably wouldn't need the blog entry or whatever it is you're reading.  And why should somebody who is pushing her knowledge to the envelope stop and meticulously think through the didactic issues that need to be addressed to bring everybody else along? 

For a person on a deadline who is implementing a DITA workflow as just a small part of her or his overall job, there's no time to work out the knowledge.  And in many cases there is no money to hire a specialist.  If you want DITA to reach down to a level below mega-enterprise, you have to accept that.  I can tell you this from experience.  As a result of my ongoing ignorance, we have implemented some things that are plain wrong, or at least not optimal.  But we're too invested in them now to suddenly fix them.  And anyway, who has the time to do it?  Pain could have been spared with more obvious access to this info-in-the-middle sort of content. 

So that's an appeal on my part...  What, why, how is a template?  What is the motivation behind the relative locations of maps vs topics?  I'm sure I can think of other questions that are open for me, but in fact, I don't have time...  Gotta get to work!  Bottom line, I'm saying there's a lack of documentation in the middle.  I have given up looking for it.

Join to automatically receive all group messages.