Event Title: DITA Technical Communications Subcommittee Meeting
Date: Monday, 20 March 2017, 09:00am to 10:00am MDT
Location: WebEx - Inquire to the list for connection information
Description
Meeting connection information is available in this action item.
This meeting counts towards voter eligibility.
Agenda
The following topics are up for discussion in the March 20, 2017 meeting:
- Approve minutes from the December 12, 2016, meeting and January 27, 2017, meeting
- Discuss the diagnostic element stage 1 proposal for DITA 2.0
- Update on programming inline discussion
- Update on separation of technical content from the DITA 2.0 core and into its own work product
- Bookmap enhancements and potential replacement in DITA 2.0
Minutes
1. Approval of minutes fo January 27th meeting deferred to the next meeting.
——————
2. Status report on troubleshooting diagnostic element
TC accepted as a stage 1 proposal. No disagreement in principle. onus on us to turn it into a stage 2 proposal
Scott Hudson - has need to distinguish between temporary (mitigation) remedy from final solution. Also looking for an auto-generated title, whether through an attribute or a different element.
Jane - suggests using attribute
Kris - using the status or the importance attribute would work. Could use a subject scheme to create a defined pick list.
Scott - I like that approach.
Bob - should decide when the draft comes out which one we’ll use. Will defer to the preference for importance.
AI: Bob volunteers to create the draft. Goal is to have it done a month from now.
———————
4. TC - activity of separating the technical content from the DITA spec
Kris - required element of stage 3 is drafting content for the spec. Stage 2 is hashing ou the strategy - migration, impact.TC needs to update the stage 2 templates and agree upon them
Stage 2 proposal is a solid design plan. Stage 3 is everything that needs to go into the spec.
Bob - that will be a draft of the implementation.
Kris - stage 2 will be ctifical. How to handle the packaging of the spec and the grammar files.
Bob - does anyone have any interest in dong this? He has ownership at the TC level but would be willing to hand it over
Scott - would be willing to help where he can.
Scott - try and get something in the next month/month and a half.
Bob - should take precedence over the troubleshooting.
Kris - thinks it’s critical to the overall TC plan for DITA 2.0. Very possible that learning and training will remain part of 1.3, and not move forward to 2.0, unless someone would be willing to step forward and reactivate the SC and own the content. TC doesn’t have the subject matter authority and knowledge.
———
5. Programming inlines / Scott’s email
Scott - the components that have been a challenge to mark up the software documentation that there aren’t explicit elements for - maybe there are some ways to better handle them in DITA. Rather than re-invent the hell are there some elements from doc-book (for example) that we can reuse and bring over into this realm . (see his email for the list)
Bob - good ideas. Doesn’t see any reason to have arbitrary differences in naming. Philosophical thing that needs to be answered about configuration about inline models and which specializations should be part o the distribution and which should be projects. Agrees that programming domain enjoys a status that it doesn’t deserve, mainly because it sin’t complete enough
Scott - depending on how far we want to go with this, we could have a more generic item, where then you can call out what that system item is, so that you introduce fewer elements. But you have the same problem in that you introduce a bunch of attributes to distinguish the items.
Jane - from an authoring perspective, it’s easier to pick a different element than to update attributes.
Bob - an argument for having two ro three domain specializations. He’d like to get guidance from the TC about the proliferation of domains and how many we should be hooking up by default. He’s sure that the docbook committee went through a detailed analysis before
Scott - docbook has a separate group of object-oriented elements and others for user-interface. When you go to package it, you can add those modules as you need them. The IA can basically include the models that they want but don’t have to include the entire software domain. Want hardware but not object-oriented, for example.
Bob - what I’d like to do is separate this activity into (1) identifying vocabulary (2) packaging considerations - domain specializations rather than modules.
Kris - I think the question of domain proliferation is a very good one. That will definitely be something that the TC will pay a whole lot of attention to. What are the things that are central enough to the profession of technical writing vs those things that aren’t? Those things that are part of the standard, very rigorous criteria will be used
Kris - huge user base that just takes the out of the box distribution. Whether there’s anything we can do about that short of having some brilliant new ways for making configuration easier for people
Bob - more of a tooling thing than a standard thing
Kris - never can get away from the questions of what’s tooling and what’s standard
Bob - best TC can do is to simplify the standard
Kris - to be cognizant of where there is critical tooling issues that are not being met
Don - programming domain - things that can be added that aren’t in either list include statements and commands. The canonical list of terms that you may need at any one time is really how you draw a circle around the particular (procedural for scripting languages or an object-oriented for compiled languages). Particularly for REST, the definitions there now are not necessarily the same that all RESTful APIs use. A complicated area and we may want to ask the TC - it would be nice if IAs could assemble
Bob - TC is actively considering the utility of the domains attribute in response to a rather lengthy piece that Robert Anderson put up on his site.
Kris - the only thing that domains do is indicate what Oasis distributed domains are integrated into a shell. If we deprecate the domains attribute, we would need to replace it with something that would serve that same function.
Scott - is that more of a DTD limitation? The need for the domain?
Kris - no, that’s a core DITA architectural issue.
Bob - I think that any organization that does a lot of programming technical documentation, really needs to configure and constrain the domains that they’re using. That will become even more apparent if we extend the vocabulary. I’m feeling pretty confident that we ought to extend the vocabulary because of the outmoded nature of the existing one. Probably ought to be partitioned into two or more domains.
Kris - Doesn’t think that the programming domain has been touched since the late 90s. The only one that’s been extended is the highlighting domain. It’s past-due to do a hard look at what’s there in the domains. How can they be extended? What needs to be retained and built-on. Inevitably I’ve constrained it for clients, getting rid of syntax diagrams. In looking at augmenting that for programming, one good place to start is probably the most common readily available specializations for programming: Java, C++ (all done at IBM). But outside of IBM, were these used and implemented? Those designs should be considered.
Scott - as a next step, would it be helpful for me to provide a proposal for the different modules that I might see - new proposed elements and the existing ones? So we can see what those modules might look like
Bob - yeah.
don - I think that what you mentioned would be useful. The kind of insight that we may need on this is: which of these are generic enough that they belong in all contexts - are all of these elements something that you may find in the discourse of a paragraph. If there are any that don’t make sense outside of a certain context, we need to know what that context is.
Are any of these members of a unique context - syntax phrase which neatly expresses the contribution of a programming phrase in a specific content (prototype, live sample, definition). Is there a particular superset that could be a container for
Scott - I mostly looked at these from the perspective of verbatim descriptions but I see your point about some of the other groupings like a syntax block.
Don - when I think about uri, that would be an example - comprised of segments and the segments may represent a remote procedure construct or a RESTful call (endpoints, resource names, etc). The uri itself could be like a syntax phrase.
Kris - need to remember that 2.0 should not be disruptive unless there’s a real need for it.
Scott - doesn’t think we should break backward compatibility haphazardly.
Kris - sees overlap with some elements that already exist in DITA with Scott’s list of elements. People will be hesitant to add elements that add authoring convenience but also add duplication.
Scott - apiname is abused and overloaded, for example - where I was looking at some of these having more distinct meanings rather than generic.
Kris - bring that up directly , for example, saying that apiname is overloaded and should be deprecated as we move to more precise domains
Don - a distinction between whether these suggested names and the legacy names are more abstract or concrete. A more abstract interpretation allows for better reuse . Would love for us to be able to add the object element to this list and make it an abstract element.
Scott - would we need a similar structure or are you talking about reusing the object element.
Don - think we‘re sunk in using the name “object” and the name “parameter”
Bob - that’s unfortunate because parameter would also be useful inside the uri element.
Kris - overlap with some of the element names that are defined in the domain.
Scott - email has such a limited area where you can use it. Tend to constrain out that domain entirely because you can’t use email anywhere except in the metadata.
Kris - (re: email) I’ve seen a number of clients integrate it into their regular topics. I think the assumptions that it’s only used in bookmap metadata isn’t one that we can rely on.
Bob - one thing that might help facilitate discussion when you come back with this would be for each element to have a column about whether there are any semantically close matches in existing DITA.
Scott - would need a description too.
Bob - a schortdesc kind of thing.
AI - Scott will provide a proposed structure for how those elements might be organized, along with the existing domains. Thinking about it from a DITA 2.0 perspective. May come up with entirely different module names or subsets.
Don - would be willing to review the draft.
——————
7. Authoring content model discussion
Bob - just have a few thoughts about this, not advocating an approach. Thinks that there’s some general principles about authoring that our out of the box distribution ignores .Thinks that it’s useful to minimize mixed content wherever possible - it tends to prune the vocabulary that authors have available when they’re writing. Takes out edge case choices that aren’t ones we want authors to make.
Scott - mixed content is hard to process. Challenge is in finding a balance - depending on the domain there might be a need for one particular group or industry - medical authoring might have different inline needs than aviation, for example. Not sure how we can approach the authoring content model.
Bob - content model for section is an example.
Kris - content authoring over specialization.
Bob - this goes back tow what we were talking about earlier in the call about configuration. It’s the same sort of issue. I certain understand why section allows tcdata. Faced with a de facto usability problem among many, that DITA is too complicated, because the configuration and constraints are too difficult for many people. A lot of user communities don’t have an IA, which makes the problem even worse.
Kris - overlaps with the question of tooling. How exactly could we make configuration contents and specialization easier to do?
Bob - definitely a topic that deserves some close study. I put together a framework to do that but it’s not one that could be shared
Scott - not just for techcomm
Kris - absolutely. Huge overlap with adoption. That may well be one of the critical areas for adoption education. What are we talking about with configuration, specialization, constraints and extensions. If you want specialization, there’s a price of complexity.
Bob - has to be some way to simplify it
Kris - I sure hope there is. The whole TC needs to think about it.
Bob - needs to go on the TC agenda.
Kris - I think so.
Bob - this problem is one of the driving factors for lwDITA
Kris - can we have a constrained simplified element set? template based specialization? Adds complexity back into the mix.
Continued discussion on this between Bob, Kris, and Scott.
No AIs.
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.
|