dita message

Subject: Tone for examples in the DITA spec

From: Kristen James Eberlein <kris@eberleinconsulting.com>
To: DITA TC <dita@lists.oasis-open.org>
Date: Mon, 20 Dec 2021 07:00:27 -0500

This e-mail relates to the following discussion in the recent DITAweb review:

Annotation	Reviewer	Status	Type	Date	Topic version
I realize examples can be hard to write. But this example gives me the opportunity to ask is there any concern that examples throughout the spec are all over the place in terms of tone. Some are definitely more real that others, some are generic, some specific, some funny, etc. In this particular case, it doesn't seem like coming up with a more applicable example would be hard.	dstevens	new	comment	14/12/2021 15:18:39
@DawnÂ(or others coming into this review), do you want to suggest a policy for examples? So far, we've only agreed on the following points: Examples should not only relate to software and hardware Examples should be realistic, if possible And I agree that this particular example sucks and recommended replacing it. I've added a separate comment so we can track that work item separately from this discussion of what examples should be like.	keberlein	updated	comment	14/12/2021 19:36:06

Annotation

Reviewer

Status

Type

Date

Topic version

I realize examples can be hard to write. But this example gives me the opportunity to ask is there any concern that examples throughout the spec are all over the place in terms of tone. Some are definitely more real that others, some are generic, some specific, some funny, etc. In this particular case, it doesn't seem like coming up with a more applicable example would be hard.

dstevens

new

comment

14/12/2021 15:18:39

@DawnÂ(or others coming into this review), do you want to suggest a policy for examples? So far, we've only agreed on the following points:

Examples should not only relate to software and hardware
Examples should be realistic, if possible

And I agree that this particular example sucks and recommended replacing it. I've added a separate comment so we can track that work item separately from this discussion of what examples should be like.

keberlein

updated

comment

14/12/2021 19:36:06

--
Best,
Kris