Chris Nitchie was not present.
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
+1 919 622-1501; kriseberlein (skype)
On 1/31/2019 1:44 PM, Nancy Harrison
1. Robert will update proposal page to show release mgmt. domain
2. Robert, Tom, and Scott will review Stan's examples
3. Alan will talk to OASIS about the issues with using Calibri as
their required body font.
4. Kris will set up at least a monthly recurring call between 2.0
and LwD spec editors.
Minutes of the OASIS DITA TC
Tuesday, 29 January 2019
Recorded by Nancy Harrison
link to agenda for this meeting:
Robert Anderson, Deb Bissantz, Carsten Brennecke, Bill Burns, Stan
Doherty, Kris Eberlein, Carlos Evia, Nancy Harrison, Alan Houser,
Scott Hudson, Eliot Kimber, Tom Magliery, Chris Nitchie
1. Roll call
Regrets: Keith Schengili-Roberts, Dawn Stevens
2. Approve minutes from previous business meeting:
22 January 2019:
(Houser, 24 January 2019)
moved by Kris, 2nd by Bill, approved by TC
New TC members: None
Kris; Bob Thomas is feeling better, able to work a couple of hours
4. Action items
21 August 2018
Kris & Robert: Perform the best edit of multimedia topics that
they can do in time available; due 18 September
11 September 2018
Kris: Review conversation with Joe Pairman, e-mails about
metadata, and TC discussion in late 2017/early 2018; summarize to
13 November 2018
Eliot: Test refactoring of grammar files
Spec editors incorporate changes from DITAweb review (Significant
progress, very near to completion)
18 December 2018
Eliot: Investigate issue re
22 January 2019
Kris and Robert: Schedule meeting to plan moving forward on
implementing complete DITA 2.0 proposals
Kris: Respond to David Hollis about his stage one proposal
Scott: Review stage one proposal about release management domain,
decide whether to move it forward
Scott; I reviewed the proposal for the release mgmt domain; I'll
keep trying to get that moving forward.
***ActionItem: Robert will update proposal page to show release
mgmt. domain proposal
Eliot: Conduct review of stage three chuning proposal (COMPLETED)
Dawn: Add CMS/DITA NA session to Frontpage Wiki (COMPLETED)
5. CMS/DITA NA 2019
Sessions from DITA TC members; are we missing any?
Kris Eberlein and Joe Gollner, DITA metadata in the enterprise
Carlos Evia, Multimedia components in DITA and LwDITA
Alan Houser, LwDITA Tools Support
Robert Anderson, What should you put on your DITA registry?, plus
co-presentation with team lead about DITA infrastructure in IBM
Scott Hudson, Farewell to style errors: Using Schematron and Vale
Stan Doherty, Managing Complexity: Making Effective Use of Sample
DITA Documentation Sets
Tom Magliery, How long is a topic?
Carsten Brennecke, Linking between outputs and project maps
Deb Bissantz, RFI to ROI: How to Prove the Value of your Component
Content Management System
Nancy Harrison, DITA packaging; past, present and future of DITA
Eliot Kimber (with Wayne Brissette): Glossary How-To
Dawn Stevens, The Balanced Scorecard: Measuring success before,
during, and after content development
Brainstorm about how we could use a table in the vendor area most
- Kris; are there any new thoughts about how to use a TC table in
the vendor area? Would it be worth having a flyer on what conf.
sessions are being done by TC members.
- Alan; might be shorter to list sessions not being done by TC
- Tom; do we have any other flyers?
- Kris; we don't have a real plan; working on it is on the agenda;
real question is 'what do we want to accomplish?'
- Stan; in adoption TC, in the past, we did a lot with handouts;
1/2 page handouts with recent white papers, etc. and the handouts
were also on the main CIDM registration table; we'll probably do
something like that again. We also used the table to look for help
with Adoption TC projects.
- Carlos; we could raffle off a copy of my book...
- Kris; that's a good idea; also, we want to be sure to have a
list of OASIS members who have emmbers at the conference, so we
can try to recruit folks from those companies to work on techcomm
- Kris; we'll probably have to nail down stuff on things in a
future TC mtg.
- Deb; will we have an on-site TC mtg or dinner?
- Kris; one of the 2; what works best for people?
[seemed more interest in dinner]
- Kris; we'll work on that as time gets closer.
6. Review of DITA 2.0 proposal deadlines
- Robert; I've updated wiki page; chunking is feb 5th, and I moved
my one on property tables (#123) to Feb. 12th.
- Eliot; no changes to my dates
7. October 2018 DITAweb review: Topics that exist in both DITA 2.0
(Eberlein, 26 January 2019)
(Eberlein, 29 January 2019)
- Tom; Kris, in your letter, there's a bunch of weird stuff below
your signature about short desc.
- Kris; this is what OASIS mail does when you have an attachment;
from my original updated email.
- Robert; btw, Kris spent days doing the LwD web review.
- Kris; had to be done.
8. Examples in DITA 2.0 spec
Additional (and more complex) examples for DITA 2.0 spec
(Eberlein, 29 January 2019)
- Stan; we have a grey area; we get consistent feedback that
people want more complex examples, but we're not sure if they
belong in the spec; so i wrote up a bunch, though I'm not sure
they're appropriate to audience. Just as an aside, when we moved
content models out of spec, that means just reading aprinted PDF
version of the spec, you may have no clue what elements are in a
- Kris; any questions?
- Alan; Stan, can you explain?
- Stan; once we removed literal content models for 2.0, if you do
a PDF printout of the element descriptions, you have no info about
content models on the page. So a benefit of having a detailed
example is that you retrieve some of the element's structure.
- Robert; I wonder about that the use case of printing out, even
as 1.3 content models were in the appendix, not on the element
- Alan; is the PDF or HTML normative?
- Kris; HTML is normative. Just a reminder; we had to remove the
content models from the spec; we just had so many errors, and we
still don't have a foolproof method for generating them. Still, we
should consider whether there's a better way of describing complex
content models. Should it be in the spec? in tutorials? what are
we trying to do in the examples? We don't have guiidelines for
this; I think they would be very helpful, and I want us to move to
having more clear definitions of how we do things; e.g., why do we
have examples in element ref topics? and what are we trying to do
- Scott; since examples could have errors or go out of date, maybe
we should put them in an appendix, or online somewhere. People
just need them to have something to work from and to train authors
to write topics. I don't know if it has to be in the spec.
- Kris; we do need to realize that primary users of the spec are
implementors, not authors.
- Robert; right, the spec's not a teaching document; it contains
rules for imp;lementors to follow. Wrt requests for more and
better examples; I think we established some guidelines for 2.0;
we want 'real-world' examples, rather than silly 'teaching'
examples. We've gone a bit towards making that more official.
- Kris; looking at our guidelines (where is that?) we don't have
guidelines for: how many examples should we include> when are
they useful/needed? when not?
- Eliot; I want examples that reflect important different use
cases or edge cases that can be confusing. Using coderef, examples
could be taken from a single repository of examples that can be
separate but used by the spec. Wherever they're put, they have be
to validated and explained.
- Kris; but examples are often not complete, so we can't ref them
- Robert; including them in the spec makes spec balloon, it also
made highlighting portions of code samples difficult.
- Tom; we need reusable text line by line when using coderef, We
need examples to illustrate as many possible use/edge cases as
possible, especially if spec is for implementors, but we have to
balance it against spec being too long.
- Robert; Eliot; what you described is what I've tried to stick
to; if there are major cases or edge cases it should be
illustrated, unless it's blindingyly obvious.
- Kris; edge case examples are useful for implementors, and user
hate them; users read them and don't understand why they're there.
- Robert; but without them, we can't get good implementations.
- Kris; so we need to do a better job of educating users about
rationale for weird examples.
- Robert; and I don't know if we've answered Stan's question; my
perspective on spec doesn't mean the community doesn't need more
and better examples; they've cried out for them.
- Kris; to close out DITAWeb review, can I get volunteers to
review Stan's examples and decide whether they should be in the
- Robert; I can work with someone.
[Tom & Scott volunteer}
***ActionItem: Robert, Tom, and Scott will review Stan's examples
- Stan; DITAWeb is really hard to use for code.
- Kris; and when I put coderefs back into a DITA topic, I had to
redo them again; shall we store them differently? maybe a
hyperlink to the TC list? or file them in github? if you put code
into DITAWeb, it tries to use it as code and excapes a lot of
- Stan; so before we do this, we might want to have a discussion
about whether to use DITAWeb to review code.
- Kris; if anyone has any ideas about a better way, let me know.
maybe googledocs? but that won't have mechanisms for id'ing end
recording disposition of comments.
- Alan; there's no such thing as a good web review tool;
googledocs is good for single documents but not for a repository.
But DITAWeb makes that stuff easier; I haven't found a better tool
- Kris; only really great web review tools I've ever used were the
internal IBM tools 'webreview' and 'ereview'; don't know of
anyting -better, DITAWeb does have pain points, for sure,
especially for editors, but I just don't know of anything better.
9. Revised style specifications for OASIS specifications and
(Eberlein, 26 January 2019)
(Chet Ensign, 28 January 2019)
Committee note redesign
(Forwarded by Eberlein, 28 January 2019)
Use of Microsoft font
(Houser, 29 January 2018)
(Forwarded by Eberlein, 28 January 2019)
- Kris; Alan brought up a body font typeface issue; we'll need to
update stylesheets in response.
- Alan; I ran ito this doing LwD committee notes; OASIS uses a
body font that is a proprietary Microsoft font. licensed for use
for Windows and Office; it's very problematic, and most likely
illegal, to use with any other OS; so either we need to get OASIS
to change their body font spec, or just let us use a different
- Tom; David Hollis sent mail suggesting a different open-source
- Alan; when I did earlier version of LwD CN, I'd brought this up
and made a request to change it, and got back an answer 'has to be
- Kris; I think the previous response was from me, during the
crunch of getting out the CN. But I think now would be an
excellent time to bring this up with OASIS. Can we task Alan with
bringing this up with them?
- Tom; Alan, pls do it
***ActionItem: Alan will talk to OASIS about the issues with using
Calibri as their required body font.
- Kris; we'll need to update stylesheets, Tom and Alan [as our
current stylesheet mavens]; let us know if you need any support on
10. Need for alignment between DITA 2.0 and LwDITA specifications
- Kris; should we defer this till 2.0 spec and LwD spec editors
have discussed this?
- Carlos; should be s set of regular calls betwee 2.0 and LwD spec
- Kris; yes, where TC comes into it is that TC needs to set gen'l
guidelines. e.g. what material needs to be the same? just
shortdescs? or do we need to make the same statements about what
is normative, with only differences being examples and LwD's info
about syntax for MDITA and HDITA. LwD editors don't want to have
an SML-first focus...
- Carlos; that sounds fair. we need to look at it more. you
provided a draft of something that might work, though we have to
look at it carefully.
- Kris; examples are non-normative; so there's no reason to share
examples. I'd like to hear from implementors, processing
expectations have to be the same for both or it won't be
- Robert; I think you can have more expectations from 2.0 than
from LwD, but where they line up, they should be the same; e.g. if
you have to process a particular element a specific way in LwD, it
has to be done the same way as 2.0; otherwise they're not
- Tom; we're working on adding LwD to next XMetal; but I'm not
sure how it's being done; seems intuitive that we should be able
to share as much processing as possible, but I don't know how much
we've actually been able to do that.
- Kris; and I'm not saying we've got to single-source everything;
but there are great advantages and it helps makes it more likely
that what's in LwD will be in agreement with 2.0, as a true
subset. But I'd like to hear from other TC member about this area
- Tom; can we hope that LwD spec itself will be small and
manageable enough that we can expect everything in LwD spec is
compatible? That is, is LwD small enough that the task of this is
- Alan; I'm hopeful; LwD has about 40 elements; we didn't take
stuff from DITA that is rocket science; LwD is mostly basic
elements; I have a maybe naive sense that it'will be reasonable to
make this work.
- Carlos; I agree; I think we can get it done.
***ActionItem: Kris will set up at least a monthly recurring call
between 2.0 and LwD spec editors.
11:57 ET close
-- Ms. Nancy Harrison