Topics

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

Kristen James Eberlein
 

I wanted to take some of the content from a recent post and turn it in a more positive direction.

Question: Where do you go for high-quality information about DITA?

My personal response:

I use the DITA specification (as published at oasis-open.org) and the DITA Open Toolkit (DITA-OT) documentation heavily. I also use whitepapers published by the DITA Adoption Technical Committee, especially the one about troubleshooting authored by Bob Thomas (https://www.oasis-open.org/committees/download.php/53516/DITA13TroubleshootingArticle_FINAL_03jul14.pdf).

You? Curious minds want to know.

--
Best,
Kris

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

Rodolfo M. Raya
 

Hi Kris,

In my computer's desktop there is a folder containing the full 1.3 specification, another one with the errata text plus a folder with errata grammars, a folder with dita-lwdita-master and a big one with DITA samples from different clients collected through the years. 

At https://ditatranslation.com/articles/index.html I published a few articles that I wrote or co-authored and are relevant for DITA localization. Some of those articles were also published by DITA Adoption TC or CIDM.

Those are my preferred consulting sources.

Regards,
Rodolfo

despopoulos_chriss
 

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 WWW.org 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.

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 <despopoulos_chriss=yahoo.com@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 WWW.org 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.

Mica Semrick
 

Instead of a wiki, why not start a github repo full of dita content about dita?

You can like the oxygen web editor to it for free.


On January 13, 2020 4:59:14 AM PST, Chris Papademetrious <chrispitude@...> wrote:
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 <despopoulos_chriss=yahoo.com@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 WWW.org 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.

Joe Williams
 

This list is the first (and often only) stop. Subscribers include the technical committee, DITA-OT developers, vendors, consultants. This is the place to get a question answered or to get pointed to an authoritative source.

Radu Coravu
 

Hi Mica,

Right, that's what I'm currently doing for the Oxygen XML Blog, it's a public GitHub project:

https://github.com/oxygenxml/blog

It contains a Gradle script to build WebHelp responsive from it:

https://github.com/oxygenxml/blog/blob/master/build/build.gradle

and it gets automatically published to Netlify whenever I make changes to it:

https://oxygenxmlblog.netlify.com/topics/welcome.html

Each HTML page as an "Edit online" link which uses Oxygen WebAuthor for editing and also a feedback form at the end of the page which uses our new Oxygen Feedback.

People who want to contribute new articles can open pull requests which when accepted will cause the web site to automatically refresh and presents the new content.

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 1/13/2020 7:49 PM, Mica Semrick wrote:
Instead of a wiki, why not start a github repo full of dita content about dita?
You can like the oxygen web editor to it for free.
On January 13, 2020 4:59:14 AM PST, Chris Papademetrious <chrispitude@...> wrote:
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
<despopoulos_chriss=yahoo.com@groups.io
<mailto:yahoo.com@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 WWW.org
<https://groups.io/g/dita-users/message/WWW.org> 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.

Julio J Vazquez
 

I'll also mention that some of what you're looking for is in Elliot's DITA for Practitioners. Yes there probably needs to be more, but using that as a reference and this group as a resource can help you greatly. 

Julio J. Vazquez