| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]
Subject: Groups - DITA TC Meeting Minutes 3 July 2018 uploaded
- From: Nancy Harrison<email@example.com>
- To: firstname.lastname@example.org
- Date: Thu, 5 Jul 2018 18:36:50 +0000 (UTC)
1. Eric will send mail to TC about his proposal for changing bookmap in response to Stafen's comments.
2. Kris will figure out a process for archiving phase one material to be removed from the 2.0 spec.
3. Kris will make sure to schedule discussion on points raised in this week's discussion of spec editing in next week's agenda.
Minutes of the OASIS DITA TC
Tuesday, 3 July 2018
Recorded by Nancy Harrison
link to agenda for this meeting:
Carsten Brennecke, Bill Burns, Stan Doherty, Kris Eberlein, Maria Essig, Nancy Harrison, Alan Houser, Scott Hudson, Eliot Kimber, Tom Magliery, Chris Nitchie, Keith Schengili-Roberts, Eric Sirois, Bob Thomas, Jim Tivy
1. Roll call
Regrets: Robert Anderson, Carlos Evia, Deb Bissantz
2. Approve minutes from previous business meeting:
26 June 2018:
https://lists.oasis-open.org/archives/dita/201806/msg00057.html (Tom Magliery, 26 June 2018)
[held till next week for minor correction]
New TC members: None
4. Action items
08 May 2018:
Eric: Consider e-mail on dita-comment from Stefan Eike and report back to TC
- Eric; Stefan was looking at element amendments; their behavior is the same as that of a whole bunch of elements inside chapter. I suggest that we move those amendments outside chapter and put them inside booklist; it shouldn't be very diffeicult. Are there any issues with my doing this?
- Kris; if you've assessed it, should we bring it up as a stage 1 proposal?
- Eric; yes, it seems like a usability issue, we could do it as part of the bookmap updates, or have a separate item.
- Kris; we need to discuss it first as a separate stage 1 item, then we could combine with the other bookmap updates if that seems like a good idea.
- Eric; I'll write a stage one proposal.
- Kris; that would be good, just fyi, a stage 1 prop is simply an email to the TC.
***ActionItem: Eric will send mail to TC about his proposal for changing bookmap in response to Stafen's comments.
19 June 2018:
Scott: Review the code examples for the glossary elements affected by issue #85, and make suggestions for changing one or more of the examples to include sup or sub (COMPLETED)
Kris: Ensure that the decisions/example/guidance are documented out of the small group spec meetings with/Robert and Carlos (COMPLETED)
26 June 2018:
Kris: Organize small group call with Bob, Bill, Maria, Robert, and maybe Carlos to discuss work on "DITA for Technical Content" (IN PROGRESS)
Bill: Start e-mail discussion of new name for "DITA for Technical Content"
Robert: Review OASIS guidelines about normative statements and present at 10 July 2018 meeting
5. Spec editing report
Robert, Kris, and Carlos met on 21 June 2018
DITA 2.0 spec editing process
https://lists.oasis-open.org/archives/dita/201807/msg00002.html (Eberlein, 03 July 2018)
[Kris gave a recap of above mail]
- Tom; can you give examples of key processing info that might be buried?
- Kris; one would be normative statements, if they're about core DITA [processing rather than that element? e.g. 'ditamaps cannot reference topic content at a subtopic level'). We might cover that in and old architecture spec topic, but not promintently enough.
- Tom; are you tracking, for any given element reference topic, that you've moved into phase 1 or phase 2?
- Kris; we're trying to do that on core element topics; we've got a spreadsheet and we're covering things. As soon as we get thru second pass, we'll want a tech review.
- Tom; do you three folks anticipate doing it all, or asking for help from other TC members?
- Kris; we're doing it all for core DITA, we'll need people for techcomm and L&T area. That's where we're asking for team effort. but if you'd like to help on core topics, we'd love it...
- Bob; btw, please confirm that 'key information', in your mail, doesn't means relevant to 'keys', unlike my initial assumption.
- Kris; yup, sorry for that.
Guidelines and examples for element reference topics
https://lists.oasis-open.org/archives/dita/201807/msg00001.html (Eberlein, 02 July 2018)
- Kris; please take a look at the above mail; we're working on having a good description of what each section is.
- Nancy; where does the extra info in shortdesc or other elements go?
- Kris; often in usage info, as we're about to discuss
- Bob; how short should a shortdesc be?
- Kris; we may not be able to use natural language in really abstract elements, but we can figure out what to do.
- Nancy; where will the conkeyref'd content live?
- Kris; right now there's a library topic with all the shortdesc info; we'll only need it for core elements where there's overlap between core and LwD.
- Kris; moving on to 'usage info' in above mail; I don't yet have a really good description of this; I hope we'll come up with a better one. In phase 1, we're using this as a catchall, where we put stuff that doesn't go anywhere else. Once we're on phase 2, we often deleting/commenting out this section. For most elements, we should not have this section, The content here often is coming from the element description; e.g.,where does element occur? what can it be used for? That is, content that's not really a description, but about how it's used.
- Tom; it's going to be hard to comment on these without seeing a lot more examples.
- Kris; these will have to evolve, and we want it to work in context with the rest of the topic.
- Keith; what is the rationale for removing best practices? I know the spec is mostly for software developers and implementores, but a critical secondary audience is tech writers. I don't see the rationale for removing best practices, since techies also often want context.
- Kris; removing that content has been out there as a plan we've had since 1.2; we want to have information in the spec tightly focused; -also, guidance for authors is uneven and often very subjective. We want to harvest this info and provide it in another document.
- Keith; yes, we need to do that, but simultaneously to releasing 2.0, and part of the 2.0 effort, we don't want to leave it out and have it forgotten.
- Scott; and would that material be considered normative or not??
- Kris; I think that would be a white paper.
- Keith; that would be the right place.
- Kris; it should come out of the TC; e.g. some best practices info has to do with highlighting domain, where we say 'don't use this if there's a more specific semantic element'; that works for techcomm, but not well for core or LwD; or another e.g.g, wrt using reltables instead of xrefs. If we consistently harvest this info, that would give us good material for another document.
- Nancy; will you archive the phase one material?
- Kris; I'll be happy to do that for what we've done so far.
***ActionItem: Kris will figure out a process for archiving phase one material to be removed.
- Kris; next section is formatting expectations; we have some hesitation as to whether this should be in the spec, but at least it should be all in one section, then we can decide whether we want to keep it in spec. We want to be sure there's no normative text in this section, and we're looking to make descriptions terser.
- Alan; how much content in this section couldn't be derived by universal publishing expectations? Are there DITA-specific formatting expectations?
- Kris; I don't know, which is one reason I want to collect and see if it's DITA-specific or just germane to publishing as a whole.
- Alan; I'd recommend having as little as possible, with only the DITA-specific stuff.
- Kris; the idea is to find out what's there.
- Chris; the base vocabulary is designed to be self-explanatory, or to be abstract, so rendering expectations are inappropriate.
- Kris; the info may have originally been for tech writers early on, but we'll put it there just to look at it; if the section is empty, comment it out.
- Kris; for the processomg expectations section; goal is to get content in a single place with right header, so that most of it can be removed and combined in another doc. BUT, all normative statements should go in this section.
- Tom; will element reference topics have subheadings to specify these sections?
- Kris; yes, subheaders are the titles shown in blue.
- Tom; you've done an impressive job of content analysis.
- Kris; we've been editing the spec for a long time...
- Tom; are there any sections/info types that you may not have uncovered, that we may need to add?
- Kris; entirely possible, if so, we need to develop descriptions of what they contain, may need new wections;. This captures what we've done so far.
- Kris; for attributes, this section existed before 2.0; the main goal is to find normative statements and move them to processing expectations section.
- Kris; next is specialization hierarchy section. topics that are part of base should maybe not even have this.
- Nancy; but if we leave this out, we don't know if it's from a topic or a map.
- Kris; good point.
- Scott; from an implementor's viewpoint, I'd like to keep that
- Tom; agree, I'd also like to keep it.
- Bob; you could say, e.g. for taskbody, say it's defined in topic/body.
***ActionItem: Kris will make sure to schedule discussion on these points in next week's agenda.
- Kris; I hope everyone has noticed there's no content model info in the spec. We have no way of generating that infomation reliably from the grammar files. We've had to modify it in every single errata release and we just can't do it correctly.
- Kris; next, there are lots of problems with examples sections; lots of bad and/or trivial examples; we could have some of the info that's now in 'usage' migrate into this section.
- Keith; I'm particularly interested in this section, so I'll volunteer on this.
[Scott, Stan also volunteered to work on this.]; ditto
- Kris; good examples are critical.
- Stan; this comes up in DITA listening sessions all the time, the need for better examples.
- Kris; expecially for stuff that hasn't been touched since 1.0, those examples can be pretty simplistic.
- Stan; one question is 'who is it for?'; sometimes it's for newbies or writers, someimes for implementors/developers, so should it be simple or complex?
- Tom; for my own work, I'm looking for varieties of ways an element may be used, so we don't lose edge cases.
- Kris; that's a good point: to clarify who the examples are for.
6. Subcommittees and Adoption TC
Report from Learning and Training subcommittee: 03 July 20018
[hold till Dawn or Amber is on the call]
7. DITA 1.3 Errata 02
21 June 2018: Opened request for OASIS to publish
03 June 2018: Asked OASIS for a time estimate
- Kris; hopefully, OASIS should get started on it this week.
8. Conformance statement for LwDITA
https://lists.oasis-open.org/archives/dita/201807/msg00000.html (Eberlein, 02 July 2018)
9. Normative statements in spec
Report back from Robert Anderson
[Hold for 10 July 2018]
10. DITA for Technical Content
- New name for this work product?
- Bill; Bob and Scott gave other alternatives, including 'Technical Communications' rather than 'Technical Content'
- Tom; I also like tech communication better than tech content; would like to have something broader than 'programming...'
- Bill; agree
- Chris; one issue is that the package is 2 diff things; some of the domains are very technical, but some are not, and then we have very general structural hierarchies.
- Tom; should we go back to info mapping and find naming that works?
- Bob; that's wired into the name DITA.
- Kris; DITA started with concept, task, & reference as part of its core, and then they were split out from the base, so it's not surprising this is difficult...
- Bob; how about DITA for tech communication?
[techcomm working group will meet again next week]
12 noon ET close
-- Ms. Nancy Harrison
| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]