Skip to content

Meeting minutes 2016 12 01

Jump to bottom Edit New page
Kristen James Eberlein edited this page Dec 4, 2016 · 2 revisions

DITA-OT Docs Call — December 01, 2016

Contents

Attendance

  • Kris
  • Peter
  • Roger
  • Shane

New contributors

As of this call, the project page lists 10 contributors.

On today's call, we welcomed Peter Ring as a first time attendee. At DITA Europe, Peter expressed interest in helping us with the docs.

Kris provides a quick conference overview:

  • DITA-OT Day, ~85 participants
  • Lunchtime meeting at DITA Europe

This was an unofficial meeting with people interested in DITA-OT documentation that we held over lunch at the DITA Europe conference in Munich.

For a summary, see https://github.com/dita-ot/docs/wiki/Meeting-minutes-2016-11-15

OT project status updates

(The December DITA-OT contributor call will be held one week later this month on December 8 due to the Romanian national holiday today.)

New issues since last call

8 new issues & pull requests were created since the last call.

Fixed issues since last call

A total of 10 issues & pull requests were closed.

Included in 2.4 release

To be released with next maintenance release 2.4.1

These issues have all been fixed since the 2.4 release at DITA-OT Day:

Of those, 5 were pull requests, 3 by Robert Anderson and 1 by George Bina.

Project planning board review

The docs issue tracker at https://github.com/dita-ot/docs/issues currently lists 18 open issues, 66 closed (no open pull requests).

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:

Discussion

Kris returns to the idea of an e-mail list for OT docs contributors as discussed during our first docs call in January.

Kris wants to make it easy for DITA-OT docs contributors to easily brainstorm and exchange ideas about how to improve the documentation. If we are going to move forward with plans for indexing, taxonomy, and a new navigational structure, we need to toss a lot of ideas around and build consensus. A e-mail list would ensure that all our messages are archived, searchable, and that people are notified of activity. If there are ways to do this in Git and Slack, please educate me! An e-mail list that anyone could join also would be a good entry point.

Roger reiterates his firmly-held belief that communication in open-source projects should happen in public alongside the code whenever possible to provide context for discussion, minimize redundancy and allow anyone to participate, including members of the core OT team (not just current docs contributors). As described in January:

Roger would prefer to use GitHub issues and wiki pages wherever possible to ensure project communication is publicly available and visible to others who join the project later.

For internal communication, the existing #documentation channel in the DITA-OT Slack team provides good context and serves well as a forum for internal discussions with other DITA-OT collaborators.

We agree to defer this discussion and revisit later as the docs team evolves and see if a consensus on communication preferences emerges.

Kris has prepared a pull request with a new grouping for the vendor list on the project home page:

  • authoring tools
  • content management systems
  • delivery systems
  • print

Peter suggests we might consider aligning this with the categories Keith Schengili-Roberts uses on his DITAWriter site:

Peter expressed an interest in indexing and suggests it may also be a good exercise in preparation for the planned top-level IA reorganization of the docs, as indexing requires us to develop a taxonomy and can be used to support faceted search in the future.

Kris suggests we begin by agreeing on an indexing strategy (indexing in prolog only vs. in-page entries), and developing a controlled vocabulary for the index to ensure consistent terminology is used.

Good resources with DITA-aware indexing recommendations include:

Shane suggests we generate an artifact (such as a spreadsheet) that lists each of the topics that exist right now, identify primary topic subjects as candidates for index terms, and begin to develop a taxonomy.

Peter supports this approach, and Roger suggests we might also use the same spreadsheet to develop the new top-level hierarchy for the docs by including columns that indicate where each topic would fit into the new hierarchy.

A simple spreadsheet might begin with a structure such as this:

| Level | Topic title | Path | Filename base | New Location | Index Entries | | --: | ------ | | --- | | | | 1 | Getting Started | getting-started/ | index | | | | 2 |   Installing… | getting-started/ | installing-client | | | | 2 |   Building… | getting-started/ | (pushed) | | |

Brief discussion on possible approaches for the initial creation of the topic overview (suitable formats, whether to generate it from map files or copy from PDF ToC, etc.). General consensus is that it should be possible to import the necessary information from the merged XML file into a Google Spreadsheet.

Shane volunteers to create the initial spreadsheet in preparation for our next call.

https://github.com/dita-ot/docs/wiki/Meeting-minutes-2016-12-01

Created 2016-12-01 16:25

View the latest DITA Open Toolkit docs at www.dita-ot.org/dev.

DITA-OT Docs Wiki

Clone this wiki locally