Meeting minutes 2017 05 04 - dita-ot/docs GitHub Wiki

DITA-OT Docs Call — May 04, 2017

Contents

Attendance

  • Kris
  • Roger

OT project status updates

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-05-04.

New issues since last call

3 new pull requests were created since the last call, only 1 of which is still open:

The remaining 2 have already been fixed:

Fixed issues since last call

2 issues & pull requests were closed.

Project planning board review

The docs issue tracker at https://github.com/dita-ot/docs/issues currently lists 20 open issues, 122 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:

Discussion

Indexing

Roger reports on results of indexing exercise from IA students, currently adding students' terms on feature branch for internal review. Further refinements will be necessary before publication, not sure if this will happen in time for 2.5 release.

Revising top-level documentation structure #121

Shane planned to take a stab at reorganizing the docs to suggest a possible new top-level organization after the last call, not sure how far he got with that, so probably unlikely to be finished in time for 2.5.

After the last call, discussion ensued on the Slack #documentation channel around how to handle changes to the source file structure of the docs as the top-level publication structure changes.

Consensus was to create a keymap for source files, and use keyrefs for all subsequent topic references as we reorganize the publication. This will allow us to leave existing files in their current physical locations for now, and move them to new locations later once we agree on the new structure.

Kris likes this approach and agrees we should strive to keep readable URLs as we refactor the folder structure.

Shane's search plug-in

Shane has been using the DITA-OT docs build to test a new DITASearch plugin for DITA-OT HTML5 transformations: https://github.com/shaneataylor/ditasearch.

A sample build is available at http://www.taylortext.com/dita-ot-docs. Shane would appreciate the team's feedback, asked for suggestions. Need to discuss whether this is something we want to use for distribution docs or site output (postponed to the next call).

Kris is comfortable w/ site output differing from distribution docs.

Antenna House

Strictly speaking, AH does not rely on OT (more like the other way around). We may need to consider revising the copy there to reflect the relationship between OT & FO rendering engines. Maybe something like this:

DITA-OT supports the following products when rendering PDF output from DITA source (AH, RenderX, FOP).

Documenting preprocessing changes

No input yet from Robert or Jarno on this, reminded during OT call, hope to have something to review soon.

Pre-OT-Day docs sprint

Roger has considered organizing a pre-conference mini-event the day before OT day. Could take the form of an OT hackathon, docs sprint, Git bootcamp or environment setup session to help new contributors get involved & set up.

Kris likes the idea, would be happy to support and attend and encourages further consideration.

Quick brainstorming on potential topics & considerations. Ideal things would be:

  • easy to work on together
  • self-contained enough that we could complete them in an afternoon
  • either low-risk quick fixes that could be reviewed in time for current release
  • or non-critical enhancements that can wait until the next release
Potential agenda
  1. Start w/ Git bootcamp to onboard tech writers new to Git
  2. Overview of controlled language for indexing, indexing guidelines from docs team
  3. Indexing workshop: participants review & create index entries for docs
Benefits
  • get tech writers involved
  • educate any devs w/r/t indexing
  • spillover into OT Day, lightning talk on indexing workshop & results
  • could feed back into OT dev if indexing reveals potential for enhancements

https://github.com/dita-ot/docs/wiki/Meeting-minutes-2017-05-04

Created 2017-05-04 16:00