dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Groups - DITA TC Meeting Minutes 29 January 2019 uploaded
- From: Nancy Harrison<nharrison@infobridge-solutions.com>
- To: dita@lists.oasis-open.org
- Date: Thu, 31 Jan 2019 18:44:04 +0000 (UTC)
Submitter's message
ActionItems:
1. Robert will update proposal page to show release mgmt. domain proposal
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:
https://wiki.OASIS-open.org/dita/PreviousAgendas
Attendance:
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
Business
========
1. Roll call
Regrets: Keith Schengili-Roberts, Dawn Stevens
2. Approve minutes from previous business meeting:
22 January 2019:
https://lists.oasis-open.org/archives/dita/201901/msg00034.html (Houser, 24 January 2019)
moved by Kris, 2nd by Bill, approved by TC
3. Announcements:
New TC members: None
Kris; Bob Thomas is feeling better, able to work a couple of hours a day.
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 TC
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 earningAggregationsTopicrefConstraintMod.xsd
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 (COMPLETED)
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 context
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 TechComm
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 effectively
- 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 members...
- 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 spec.
- 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
https://wiki.oasis-open.org/dita/DeadlinesDITA2.0
- 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 and LwDITA
https://lists.oasis-open.org/archives/dita/201901/msg00036.html (Eberlein, 26 January 2019)
(UPDATED) https://lists.oasis-open.org/archives/dita/201901/msg00054.html (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 element.
- 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 description page.
- 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 there?
- 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 by coderef.
- 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 spec?
- 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 stuff.
- 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 yet.
- 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 committee notes
https://lists.oasis-open.org/archives/dita/201901/msg00037.html (Eberlein, 26 January 2019)
https://lists.oasis-open.org/archives/dita/201901/msg00045.html (Chet Ensign, 28 January 2019)
Committee note redesign https://lists.oasis-open.org/archives/dita/201901/msg00048.html (Forwarded by Eberlein, 28 January 2019)
Use of Microsoft font https://lists.oasis-open.org/archives/dita/201901/msg00053.html (Houser, 29 January 2018)
Spec redesign https://lists.oasis-open.org/archives/dita/201901/msg00049.html (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 one.
- Tom; David Hollis sent mail suggesting a different open-source font.
- 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 Calibri.'
- 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 this.
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 editors.
- 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 interoperalble.
- 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 interoperable.
- 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 manageaable?
- 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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]