-
Notifications
You must be signed in to change notification settings - Fork 97
Meeting minutes 2017 08 17
- Attendance
- OT project status updates
- New issues since last call
- Fixed issues since last call
- Project planning board review
- Discussion
- Kris
- Peter
- Roger
- Shane
The DITA-OT contributor call was held immediately prior to the docs call. Meeting minutes are available at https://github.com/dita-ot/dita-ot/wiki/Meeting-minutes-2017-08-17.
- DITA-OT 2.5.2 was released on August 1. See http://www.dita-ot.org/2.5/release-notes.
- 2.5.3 likely to land later this month.
1 new issue was created since the last call:
A total of 2 issues were closed.
The docs issue tracker at https://github.com/dita-ot/docs/issues currently lists 16 open issues, 131 closed.
Our GitHub Projects boards show the status of issues currently associated with each release milestone and serve as the primary planning overview for upcoming releases:
Roger reports that the initial offer for a meetup venue has since been canceled, so uncertain whether we'll be able to find a suitable location near the conference venue in time to organize and publicize the event.
After brief discussion, we agree to drop the idea for this year, gauge support during the conference and consider it again for next year with a bit more time.
Roger points out that we need to get a sense of the docs work required for the 3.0 release, and how we can best prioritize and distribute the effort.
Initial discussions suggest that the new preprocess2 routine will not have major docs impact; if users haven't customized preprocess it won't affect them much, but we'll need to provide a few details for those who have. Roger's understanding: we'll need to revise sections that deal with preprocessing flow, either add new descriptions or replace old content with new. Robert has suggested we highlight preprocess2 as the preferred new method, but leave description of old preprocess.
Assuming Jarno's Markdown plug-ins are bundled with core for 3.0, we'll need to document them as well. Roger will be able to cover that, as he has worked with the plug-ins and has presentation materials that can probably be repurposed for the docs.
Robert suggests a new topic on Lightweight DITA to acknowledge the format and say what (if anything) we're doing with it in 3.0. Kris agrees this would be important given recent LwDITA momentum in TC/OASIS and says she may be able to contribute content for that.
With little more than 2 months to go, we need to assess whether we'll be able to revise the top-level documentation structure as planned in #121.
Kris suggests implementing the old IBM infocenter guidelines as a basic content model:
- installing
- getting started
- configuring
- developing
Shane sees 3 primary audiences for the docs, each w/ different needs:
- tech docs managers — what is OT?
- user — how to install & use?
- devs — customize & troubleshoot
Shane suggests the primary goal of the top-level structure is to orient first-time users and guide them to initial success. ToC may be better tuned to novices, as experts may be more inclined to search.
Kris adds that a better (more task-oriented) structure will also serve us, to help identify where pieces are missing and docs are light. This approach would help us gather use cases that are compelling enough but not well-served by current docs (or structure).
Shane: basic use case like creating a custom header is currently there, but somewhat hidden, better to promote & extend.
Kris suggests meeting in person w/ Shane to brainstorm on top-level docs structure. Shane says he may be able to bring in a former colleague (Misti Pinter) to join in the discussion and get a fresh perspective.
Shane began drafting a revised structure back in April, will try to revisit that before next month's call: https://github.com/shaneataylor/docs/blob/121/userguide.ditamap.
As with the top-level reorg for #121, we need to decide whether we can realistically deliver a solid indexing baseline for the next release (see #53).
After initial discussions in recent calls, Shane began working on a basic taxonomy a few weeks ago: https://github.com/shaneataylor/docs/blob/indexing/index-taxonomy.ditamap.
This defines keys as a controlled vocabulary in a subject scheme map that defines the taxonomy. Taxonomy in classification map makes users less reliant on familiarity w/ terminology used (they can pick from taxonomy).
Shane wonders whether oXygen supports/presents keys when authoring index entries?
Kris cautions we'll need to watch out for issues w/ OT support of classification domain & subject scheme.
https://github.com/dita-ot/docs/wiki/Meeting-minutes-2017-08-17
Created 2017-08-17 18:08
View the latest DITA Open Toolkit docs at www.dita-ot.org/dev.