Event Title: DITA Technical Communications Subcommittee Meeting
Date: Monday, 01 May 2017, 09:00am to 10:00am MDT
Location: WebEx - Inquire to the list for connection information
Description
Regular business meeting
This meeting counts towards voter eligibility.
Agenda
The following topics are up for discussion:
- Approve minutes from the April 2, 2017 meeting
- Report on DITA NA
- Inlines discussion. Review action items assigned to Scott and Don. Continue discussion on developing initial models.
- Separation of technical content from the spec.
An update went out ot the list on April 8th. Feedback?
- Troubleshooting model. Straw model posted in a public repo on bitbucket (https://bitbucket.org/bob_thomas/com.tagsmiths.ditats2)
Minutes
OASIS DITA Technical Subcommittee meeting minutes
Monday, April 3, 2017
Recorded by Jane Credland
—————————
Attendees
Bob Thomas
Don Day
Scott Hudson
Jane Credland
Skipping next meeting - reconvening on May 1st.
—————————
1. Approve Minutes
moved by Bob, seconded by Scott - motion passed
—————————
2. Action Items
Bob - Troubleshooting diagnostic feature proposal - no work on this so far. No commitment to delivering it in the next month or so.
—————————
Scott - Programming inline element expansion. RNC file is available to review element names. Talking about providing multiple modules that people can subscribe to; they may not want all the inlines but only hardware and web services, for example. He’s in the process of creating different ones for hardware, web services, software and programming, and basically looking at two new domains.
The first domain sent this morning is the hardware domain. No formal document, just the compact syntax to give
1) System item - comes directly from DocBook standards. May be too abstract. It does tie a number of choices that are called out in the type attribute, which Robert isn’t a huge fan of. One way to cover a lot of ground by having a more abstract element.
Basically, it can contain any word. Then you classify what kind of system item through the Type attribute plus the enumeration.
2) key combo - a grouping of one or more keys and one or more uicontrols. For example, Ctrl+Alt+Delete or any other kind of key combo. modified from DocBook. Separate element called key that is a phrase level wrapper to document the name of the key. Key combo, if you need to document forcing a browser refresh, for example. DocBook also had an attribute for specifying whether you’re clicking, double-clicking, right-clicking, etc.
Bob - one potential issue is getting uicontrol from another domain.
Jane - potential confusion with key ref and key.
Bob - may need to prefix with kb for keyboard.
Scott - named the domain, hw-d. So, it would be hw-key, for example.
Don - how would this apply to touch or dictation, such as iPad or Google Glass, where you’re interacting by voice command.
Bob - that might make more sense as an extension of the UI domain.
Don - need more separation of interface from actions. The existing element of system output describes an exact sequence of operations but doesn’t define the interface type. Whereas menu cascade defines the interface (breadcrumbs). As a writer, determining what am I documenting, wondering what is the right mark-up to use. Not clear from this markup. One of the usability issues that writers have.
Taking a model approach - here’s what needs to happen from the system; view is what you see, syntax which is the concrete things you need to provide (speak, type, touch) in order to initiate that interaction.
Scott - kind of like user input, but more like input method.
Don - I often use user input when I’m trying to describe dialog. From a user experience POV, we sometimes miss that the interactions are a dialog.
Scott - where do we think that would live? Would that be in the UI domain or in a separate interaction domain.
Bob - I think that would warrant its own.
Don - to what extent do we need to provide all three of these in a single domain. Is there ever a time when you describe what you see on the screen without describing what you need to type when you
Scott - instead of calling it hardware domain, perhaps an interface
Jane - need to avoid confusion; initial thought with hardware domain was that it related to documenting hardware.
Don - not comfortable with advancing anything yet. But doesn’t have a proposal, only questions. Just trying to delineate whether this is our problem or someone else’s problem. I don’t want to boil the ocean but we don’t want to add confusion if a writer doesn’t find the offered markup not intuitive for the use.
Scott - just wanted to throw something up to see what sticks. This has been a good way to look at some aspect; I agree that even the phrase hardware domain… still user interface because it’s still user interaction.
Don - we could use the terminology that’s used for responsive web design where you have inputs and sensors. That’s part of the terminology. May or may not apply strictly here. The things you interact with are not necessarily hardware, they’re part of the interface. So keycap is a system interface, just like the touch screen and a microphone.
Bob - what do you think about letting the DocBook team know about what we’re doing?
Scott - I can be out DocBook liaison, will bring it up at the next meeting.
Bob - I’d like to do that just so there isn’t any animosity. More like a courtesy more than anything.
—————————
3) Web Services Domain
Scott - shared rough draft on screen. Will cover Web Services, SOAP and REST.
Elements (alpha order)
binding
datatype
endpoint
message
method
portType
port
request
response
schema
security (authentication type)
service
Don - what about RPC based services.
Scott - intended to be a generic container for how you would do that request. Would protocol be a better name?
Bob - may want to do this in the object-oriented stuff. We would want method there too.
Don - question was around thinking about “verb” for REST. Maybe what’s missing is that it would support services that are activated by parameters rather than URL; trying to think of the proper name for the stuff that followings the question mark at the end of a URL.
Scott - we already have parmname and parameter.
Don - do we want to enable naming segments for their meaning? An example being when you have the url to go from the endpoint one of the intermediate segments, that segment has a specific meaning to the collection activity that the web service does at that point.
Scott - you’re basically talking about the name/value pair.
Don - probably has a specific web service. In a RESTful design, that segment very likely has a defined behavior. It’s an endpoint that creates a collection rather than a discrete object.
Scott - would that be covered under endpoint in that instance
Don - we may want to go back to the terminology around RESTful URL design, because the way that I’ve been treating them is that anything short of the single thing that’s name is not an end point but a collection leading to the endpoint (of which the endpoint is a member).
Don - does it hurt the design to add segment as one of the options?
Scott - I don’t think so. We don’t already have an element for that.
Don - in the example, if you were documenting everything not including there, what defines the part of the URL not including the endpoint.
Scott - the endpoint could be the entire string was well. It depends on what you’re defining as your end point.
Don - so the endpoint could be either a collection or a report?
Scott - I’d almost think that pair is a segment
Don - it’s not a URL segment though. Anything in the parameter entity is basically like a processing instruction in XML. It’s how you pass extra information to the processor, but the identity should be cleanly defined in just the URL itself.
Scott - reviewed the URI scheme - URI
Don - used to specify concrete syntax. The definition of the segment values. Path is the thing that we want to pick apart. They’re using scheme as the mailto part, so we won’t use that.
Scott - sequence of segments, so I think segment is familiar
Don - in API documentation do we tend to treat segments as discretely defined parts of the API? I don’t recall if you had path in your design.
Scott - I didn’t. I think I agree the segment has some, but path
Don - path would be one or more segments
Scott - I don’t want to overload any of the terms. If you were to try to document path would you be able to do this from this list of elements or would you need something separate.
Don - at this point, I don’t know. If you don’t mind, would you bring up the documentation for the NING API. People tend to recommend different APIs as being good for different examples. This is one that I see as a nice clean example. Tend to define each segment in a multi-segment request and that may help determine whether segment should be a repeating member in a path, and therefore a new segment.
Scott - will continue discussion on list.
AI: Scott to let the DocBook committee know that we’re looking at reusing their enumerations and descriptions.
AI: Don to write something up about sessions, dialogs, interactions, and just try to provide some framework for having a discussion about where we draw the circles around these.
—————————
3. Separation of technical content from the core DITA specification
Bob - Robert had some feedback on the updated feature proposal from the TC. Does anyone have any objection to me incorporating his comments or have any additional comments? Probably not going to be ready to take it to them until next week.
Scott - I agree with his comments.
—————————
4. Bookmap and publication map discussion.
Bob - nothing new to add to that. Would also like to see what happens on the TC with this.
—————————
5. Glossary
Bob/Scott - nothing further to say
—————————
6. Additional Items
Bob - slated to talk about the TechComm SC on DITA North America. Will talk about what we’re working on get feedback from people at the session. My feeling on it is that it will be sort of like a listening session, only I’ll be doing a lot more talking.
Scott - I think that soliciting feedback on items that people would like to see
Bob - would like to talk in some depth about the initiatives we’ve got going on (programming, troubleshooting, potential enhancements to bookmap), and then may talk a little bit about TC direction for distancing the spec a little bit from being so content model heavy. I also want to talk a little bit about the fact that we’re still very interesting to see what we can do about providing a better authoring environment, even though we don’t have any concrete plans. There are dependencies on us before we can get into any discussion about what will happen with the technical issues (domains, etc) about how we can go ahead and address things about simplifying configuration and constraints.
Scott - sounds good to me.
Scott - if I’m available, I’ll try and attend
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.
|