dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Groups - DITA TC Meeting Minutes 14 February 2023 uploaded
- From: Nancy Harrison<nharrison@infobridge-solutions.com>
- To: <dita@lists.oasis-open.org>
- Date: Fri, 17 Feb 2023 22:41:16 +0000 (UTC)
Submitter's message
ActionItems:
1. Stan will develop add'l example for diagnostics-general element.
2. Tammy will open up a pull req on release mgmt. topics.
3. Kris and Robert will look at Stan's pull req and give feedback.
4. Kris will reach out to Bill&JKeith to check on status of glossary.
5. Dawn and Kris will work together to redefine responsibleParty element; new shortdesc and examples.
=================================================
Minutes of the OASIS DITA TC
Tuesday, 14 February 2023
Recorded by Hancy Harrison
link to agenda for this meeting:
https://wiki.OASIS-open.org/dita/PreviousAgendas
Attendance:
===========
Robert Anderson, Tammy Crowley, Stan Doherty, Kris Eberlein, Nancy Harrison, Zoe Lawson, Dawn Stevens, Kathryn Torriano, Frank Wegmann, Todd Thorner, Jim Tivy
Business
========
1. Roll call
Regrets: Eliot Kimber, Scott Hudson, Keith Schengili-Roberts, Eric Sirois
2. Approve minutes from previous business meeting:
07 February 2023
https://lists.oasis-open.org/archives/dita/202302/msg00010.html (Harrison, 08 February 2023)
Kris moved, 2nd Zoe, approved by TC
3. Announcements none
4. Action items and volunteer tasks
[no updates; see complete list in agenda]
5. Technical content review C: Programming, software, and UI domains
https://lists.oasis-open.org/archives/dita/202301/msg00005.html (Anderson, 09 January 2023)
Status of review
Participation: Eliot, Kris, Robert, Tammy, Zoe, Stan, Bill, Frank, Nancy
Update (Anderson)
[no updates, Robert expects to be able to go back to working on this soon.]
6. Techical content review D: Hardware, markup, and XML mention domains
Opening of review
https://lists.oasis-open.org/archives/dita/202301/msg00021.html (Eberlein, 24 January 2023)
Status of review
Participation: Kris, Robert, Zoe, Stan, Dawn, Frank, Nancy
Update (Anderson)
[on hold till next week]
7. Base review T: utilities domain and sorting
https://lists.oasis-open.org/archives/dita/202301/msg00030.html (Eberlein, 30 January 2023)
Questions from review:
https://lists.oasis-open.org/archives/dita/202302/msg00002.html (Eberlein, 07 February 2023)
Update (Kris)
- Kris; I sent email to the list after last week's call about imagemap, in particular about DITA-OT output and Oxygen error messages for them. Our reviesd content is correct. but I haven't gotten a chance to finish this up. I should be able to close it out next week.
8. Review E: Troubleshooting
https://lists.oasis-open.org/archives/dita/202302/msg00005.html (Eberlein, 07 February 2023)
Status of review:
https://lists.oasis-open.org/archives/dita/202302/msg00021.html (Eberlein, 14 February 2023)
- Kris; I'm updating this now. we also need to talk about changes to responsibleParty element.
- Kris; we talked about the quality of examples. The challenge of examples is that we want them to be high-quality examples, but they can't be as complex as actual code is likely to be. And another issue is that when an element should have an example, we prefering in most cases to not just xref to another topic. When 2 elements are intrinisacally connected, e.g. troublebody and troubleshooting, or responsibleparty and remedy, then we might want to reuse one example. But mostly, it's better to have individual examples. Also, when we xref to an example, we lose ability to use bold highlighting on the element we're discussing, and that's a problem.
- Robert; agree; this is hard to settle on as a policy; it's subjective. Sometimes you need a large example, sometimes not.
- Kris; every time we talk, we come up with new editorial guidelines
9. Stan's comments about troubleshooting
https://lists.oasis-open.org/archives/dita/202302/msg00008.html (Doherty, 08 February 2023)
- Stan; basically, I had the following issues:
1) single cause-remedy pairs are rare; mostly one-to-many and many-to-one.
2) not just writers involved; usually support has to sign off on these topics; it's much more focused than info in a diagnostics section, which only has diagnostics info. Support orgs are legally liable for what's in troubleshooting topics.
3) terminology; we need to decide on our terminology here,
4) there are opportunities outside the spec to talk about this kind of topic. It's the #1 collaborative content in the orgs I'm in. DITA can tout that our content is the best in the industry for e.g., feeding chatbots.
- Kris; I have some reaponses to your comments, but anyone else
- Dawn; I'm on same page as Stan; I tried to suggest possible rewrites and made suggestions on that.
- Kris; cause-remedy pair is language that was heavily used in 1.3, and got carried over to 2.0. I've tried to update language where it's not right; but we need to change terminology to reflect facts. In 2.0, adding diagnostics made troubleshooting topics much more popwerful, but language doesn't reflect that.
https://lists.oasis-open.org/archives/dita/202302/msg00009.html (Eberlein, 08 February 2023)
https://lists.oasis-open.org/archives/dita/202302/msg00011.html (Eberlein, 09 February 2023)
Summary
https://lists.oasis-open.org/archives/dita/202302/msg00015.html (Eberlein, 13 February 2023)
- Kris; integrating with other utilities is where this gets really exciting, but it's out of scope for spec; much more suited to a CN; we have more leeway in a CN to talk about new audiences and what can be done; but have to be careful what goes into spec
- Kris; Stan, would you be interested in helping author an updated CN?
- Stan; maybe. That is, I'm interested but it's a timing issue. OTOH, you and I are doing a presentation on troubleshooting at ConVex, we might learn more there.
10. Mixing diagnostic, cause identification, and remedy information together:
https://lists.oasis-open.org/archives/dita/202302/msg00016.html (Eberlein, 13 February 2023)
- Kris; see my email; is original screen capture what you were referring to as problem?
- Stan; yes, kind of. most users don't know how to identify actual symptiom.
1) how do yuo diagnose a symptom 2) what are possible causes of that symptom, 3) what are solutions for possible causes.
- Kris; I've had same experience; the topic is very flexible, but that means orgs have to do a lot around specialization and constraints to make it work correctly for their situation.
- Kris; so we have the design as we've approved it. We don't want radical changes to that. have choice of what we put in examples in spec. It's a fine line; we won't have examples of fully refined troubleshooting content, because they're too complex. OTOH, we need examples we can create withuout ridiculous amounts of work, and ones that people can easily read/understand. So look at second screen capture in my mail, is this better? it has a diagnostics-general element that gives a table that sends users to the right info for each cause.
- Stan; I think some intro text would work well here, e.g. "here's an example for multiple symptoms, and here's an exampel for just one symptom."
- Dawn; I diagree; most of my clients do try to put multiple causes for the symptoms they see, so I see this type of table all the time.
- Robert; just tangentially, there is also sometimes a need for a general topic
- Kris; it's very flexible, different folks use it in very different ways. I wonder if best thing is to have 2 examples, one being current one, and one more specific, one symptom with many causes and diagnostics to evaluate them.
- Stan; that would be great. trying to get troubleshoting as a building block for different circumstances.
- Kris; could you develop an example for your type of situation?
- Stan; yes, I can
***ActionItem: Stan will develop add'l example for diagnostics-general element.
- Kris; when we do our second review, can you keep an eye out for this problem?
- Stan; will do.
11. Editorial work on DITA for Technical Content 2.0 element-reference topics
NEW How much "context" to show in examples?
https://lists.oasis-open.org/archives/dita/202302/msg00023.html (Eberlein, 14 February 2023)
- Kris; see the email; this is something we only want for components of structural specializtions.
- Robert; it's important not to have overlong examples, so snip the code as necessary. If you really need something else, put in a code comment.
- Kris; I can add this to editorial guidelines. comments
- Tammy; that makes sense. So, e.g., if I'm doing cause element, I'd just do an xref to the remedy topic?
- Kris; no, I wouldn't do that; I would want cause and remedy both highlighted.
- Tammy; good, I'd rather not as well.
Editorial assignments, deadlines, review maps
https://lists.oasis-open.org/archives/dita/202301/msg00035.html (Eberlein, 31 January 2023)
- Kris; what about release mgmt?
- Kathryn; it's about ready
- Kris; OK, open up a pull request against DITA repo.
***ActionItem: Tammy will open up a pull req on release mgmt. topics.
- Kris; Stan?
- Stan; I sent a trial pull requset; if it works, should be done tomorrow.
***ActionItem: Kris and Robert will look at Stan's pull req and give feedback.
- Frank; I'm half thru mine, so will have to bump it another week; it's its own universe. And there are a number of non-working examples, so I need to make them work, Also, a bunch of editing questions, so I should be done by next weekend.
- Kris; best thing to do with places where things are mixed up, add a draft-comment with your pull req, and Robert and I can look at it.
***ActionItem: Kris will reach out to Bill&JKeith to check on status of glossary.
- Kris; what about bookmap?
- Tammy; no dates as yet, but I think we whould go to bookmeta next, then structure.
- Kris; I'll add an add'l review map for those elements, and update email to list updating table we're using.
- Tammy; bookmap has over 60 topics, so better to split it.
Editorial guidelines
https://lists.oasis-open.org/archives/dita/202301/msg00036.html (Eberlein, 31 January 2023)
General resources:
Recording of 20 December 2022 session
https://lists.oasis-open.org/archives/dita/202212/msg00033.html
GitHub education that the TC did in 2018
https://lists.oasis-open.org/archives/dita/202212/msg00034.html (Eberlein, 21 December 2022)
Status?
Other:
- Kris; another item, responsibleParty element is element that can ony appear as child of remedy. - name of person or team who should be perforing the remedy. Because of this, I think p as base doesn't make sense as specialization base, I think it should be data. OTOH, Dawn's clients use it for more general info. If we were back in design phase, we should redesign it. but we should at least redefine it so it's clear that it could have more general info.
- Nancy; agree, if that's how folks are using it, then we should desribe it that way.
- Kris; so we'll broaden the definition of the element.
***ActionItem: Dawn and Kris will work together to redefine responsibleParty element; new shortdesc and examples.
- Kris; hope to have a new vesion of troubleshooting review out by Thurs.
12 noon ET close
-- Ms. Nancy Harrison
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]