Event Title: DITA Technical Communications Subcommittee Meeting
Date: Monday, 12 June 2017, 09:00am to 10:00am MDT
Location: WebEx - Inquire to the list for connection information
Regular business meeting
This meeting counts towards voter eligibility.
The following topics are up for discussion:
- Secretary and meeting venue
- Inline modeling efforts
- Separation of technical content from the spec
OASIS DITA Technical Subcommittee meeting minutes
Monday, May 15, 2017
Recorded by Jane Credland
Minutes from May 2, 1027 meeting approved
Scott wasn’t here so item was tabled
3. Report back from TC meeting on separating technical content
Bob: spent a fair amount of time talking about it without much concrete direction. TC would like us to have live links to the HTML when we get into discussing element. Discussions of attributes should resolve to the page. Should be fairly straight-forward. When we produce something, it will look as if we have cross-references.
PDF linking is not all that robust, especially across publications. This is a problem that we’ll hammer out on the TC. Elliot wasn’t very optimistic that we’ll have working PDF-to-PDF linking for this. Still to be decided.
He will be updating the feature proposal based on TC discussions and will bring that back to the SC. Most difficult option to do, but important for usability reasons.
Kris: Robert is thinking of different ways to do the attributes in DITA 2.0.
Robert: Doesn’t think it will have an impact. Would like things to be more organized in a more user-friendly way. Would still be organized in a base that the TechComm package would need to link to.
Kris: would it be worth considering, if for 2.0, the attribute information was consolidated more in topics and less in individual reference topics. Is there a reason why maybe those topics couldn’t be duplicated in the TechComm spec.
Robert: I think an appendix would be appropriate here as it’s basically reference material. And the TechComm spec isn’t what’s defined as normative content.
Kris: thinking about usability and attribute design
Robert: probably a really good thought. If we can design the attributes in a way that the descriptions are minimal and can be bundled with any other version of the spec, I think that might go a long way to resolving the usability issue.
Kris: if we have an alphabetical list of elements, include attributes with that.
Bob: would want to avoid having links out of the attribute
Robert: the links would have to be to the HTML. Would never be able to avoid having links from the keyref definition to more information bot the keyerfs. Hopefully links to the completed baes spec rather than the internal.
Bob: sounds like a good trade-off, satisfying most users.
Robert: I think so. I really like the idea. If you can have an internal link to an appendix with the core definition of the attribute there, it would be better than HTML links.
Bob: about the best
Kris: well worth taking the DITA 1.3 or 1.3 Errata topics and prototyping up a spec based on that existing content and see what it would look like and feel like. As we’ve been talking about redesign, we’ve been talking that what we want to do for the base spec is to set rules and guidelines and have those be echoed by any other spec. So probably getting someone from the TechComm SC intersecting with those of us working on the redesign of the base spec would be a good idea.
Kris: I think doing the mock-up would be a good reality check.
Bob: it would certainly make the decision process a little more concrete. At a certain point, these discussions get very abstract… my idea (understanding) can be very different from someone else’s.
Kris: at the end of the day, we’re delivering non-abstract content.
Kris: one additional question: let’s make the assumption that the plan is to go ahead with separate products for base and TechComm. Where do we want the base files to live? In the same github repository.
Bob: they have to be
Kris: in the same as the base spec? Yes, they have to be if we’re reusing content.
Kris: question is mostly related to administering the repo.
Bob: Probably want the technical content to be close to the top of the tree. Might even go to the same node as the base spec.
Robert: we have to decide whether they even belong in the same repository if they’re two different documents with different release schedules.
Kris: if we have separate deliverables and work products for all these, do we want to amalgamate them on one repo or have a separate one for each spec.
Robert: I would say different repos.
Kris: I think we can have as many repos as we want. What I would suggest is that we do the same thing for the repos as we’re talking about for the spec, have standard guidelines for organizing content, style guide, and usage as git.
Bob: would want to bring the base in as subcontent to the TechComm content.
Bob: pull the attributes into an appendix, mainly for convenience for the PDF reader. In the HTML, all of the links are going to resolve, including the link dependency chain.
Kris: Any concerns from people [at DITA NA] or was it too abstract.
Bob: it was the inlines where it happened
Robert: many people were silent, which could be a sign of concern, but there’s reason for concern.
Robert: Realistically, for usability purposes, somebody could publish a version with the base. At that point, the only thing left in the base is the feature stuff. Then again, if we go that far, why not publish the base as a set of appendices.
Bob: Basically, we’ll be removing the architecture portion of it. I would think the majority of technical writers look at the architecture portion and recoil in horror.
Kris: possibility of having a part 0, being a high-level overview of DITA. That could be the kind of basics of paragraphs/lists, etc., and could be repurposed in a TechComm appendix.
Robert: TechComm shouldn’t introduce its own architectural stuff.
Kris: I think also in our group that’s doing the redesign, we may have some differing ideas about what should be in the part 0.
Bob: whatever the TC redesign is, TechComm can accommodate it.
Kris; it would be good to have someone involved in the redesign who thinks about the TechComm needs and the TechComm spec. Most of us are really focused on the base.
Bob: When do you meet next?
Kris: Don’t have a meeting scheduled. We are due to give a report back to the main TC
Bob: Why don’t you include me in that activity?
Kris: I’ll do that and try to send you copies of the emails we generated on this so far, or at least the one I sent out, trying to provide a summary.
Kris: Will register Jane as the secretary for the SC. (As chair can do that for all SCs).
4. Troubleshooting Straw Proposal
Bob: Content model for Diagnosis is a section specialization. Allowed a mixture of Steps and Steps-Unordered in Diagnosis. Left out Steps-Informal. Could easily put it back in if needed.
Bob: have gone ahead and put together a straw proposal and DTD syntax that puts together a Diagnosis element for troublebody, and looked at the required elements. There’s no longer a required troublesolution, for example.
The Diagnosis element is a section specialization that doesn’t allow mixed content and has the restriction that the title has to be first.
Robert: that sounds along the lines of what I would have expected.
Bob: got rid of the concrete requirement for at least one <steps> or <steps-unordered>, in case someone wanted to conref a Remedy.
Robert: that one caused some confusion in San Diego.
Bob: content model for Remedy is so strict that you can’t really do anything with
Owner: Mr. Robert Thomas
Group: DITA Technical Communication SC
Sharing: This event is shared with the OASIS Open (General Membership), General Public, and OASIS Darwin Information Typing Architecture (DITA) TC groups.
Public Event Link
- Learn more about subscribing here.
- View the DITA Technical Communication SC calendar here.
- You may receive future notifications with updates to this event. Update the event on your calendar by accepting the changes.