[dita] The specâs alternative purpose

[Kristen James Eberlein <kris@eberleinconsulting.com>]

Meant to send this to the TC, not just Zoe.

Best,
Kris

-------- Forwarded Message --------

Subject:	Re: [dita] The specâs alternative purpose
Date:	Mon, 22 Nov 2021 19:32:03 -0500
From:	Kristen James Eberlein <kris@eberleinconsulting.com>
To:	Zoe Lawson <zoelawson17@hotmail.com>

Hi, Zoe.

We know that people other than implementors use the spec. And we have committed ourselves to making the following parts of the spec as accessible as possible to end users:

• Short descriptions
• Examples

However, the spec cannot be a user's guide. In an ideal world, the DITA TC also would publish a primer about DITA that would serve as a solid, spec-approved introduction to DITA -- but we don't have the time and resources.

We had a lot of solid discussion about this back when we were developing the template for the element-reference topics. Can anyone help locate some of those e-mail threads?

And Zoe, thank you for your very solid and helpful reviews of the element reference topics!

Best,
Kris

On 11/22/2021 3:17 PM, Zoe Lawson wrote:

Greetings!

Again, I have my standing conflict, so I may not be able to raise this tomorrow.Â

I completely understand that the spec has a particular purpose to define the standard.Â

However, the spec does a lot more than that.Â

Many editors reuse parts of the spec as help within their UI (Eg Oxygen) or minimally point to it in the help (Adobe FrameMaker). Unfortunately, Iâm not familiar with other editors.Â

Itâs not âour jobâ to make the spec the users guideâbut I think the world is often using the spec as a users guide, whether we intend it or not.Â

I know I have the spec bookmarked, and thatâs where I go to learn about DITA. Iâm usually working with smaller companies that donât have money for training, etc.Â

As we review and revise the spec do we want to consider the writers who will be reading the short descriptions in the Oxygen UI as how theyâre learning about DITA? Or following links to the spec âfor more informationâ?

And I completely understand if the answer is âoutside of scopeâ.Â

Zoà LawsonÂ

(she/her)