Meeting minutes 2016 06 02

DITA-OT Docs Call — June 2, 2016

Contents

• Attendance
• OT project status updates
• New issues since last call
• Fixed issues since last call
• Discussion
• Backlog review
• Issue prioritization

Attendance

• Juliane
• Kris
• Roger
• Shane

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-2016-06-02.

• 2.2.5 hotfix was finalized on Monday, May 9.
• 2.3 was released May 29 — see http://www.dita-ot.org/2.3/release-notes.

New issues since last call

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

Fixed issues since last call

A total of 12 issues & pull requests were closed.

Of those, 3 were pull requests:

• #96 by George to mark generated topics with @outputclass="generated"
• #97 by George to test the oXygen Web Author workflow
• #100 by Robert with input for the 2.3 Release Notes

The documentation of args.hdf was improved for #98 to describe how a <div> wrapper can be used to insert multiple elements in HTML page heads.

The remainder was mostly changes for long-running issues that were completed for the 2.3 release, including:

• #29 – Add info on migrating to v2.x
• #43 – Migrating PDF customization folders to plugins
• #57 – Link to the PDF plugin generator
• #59 – Remove “Tested platforms and tools”
• #69 – Add relevant content from pdf2 ReadMe files
• #70 – Extend section on “Customizing PDF output”
• #75 – Rearchitect "Creating plug-ins" chapter"

Discussion

Roger points out that George's changes for #96 would allow us to visually distinguish generated topics in site output. Kris likes the idea, need to consider alternative presentation, perhaps dimming topic titles or prefixing via CSS ::before or ::after pseudo-elements.

Kris points out that the new Edit links in the dev docs are easy to miss and that we may want to alter presentation to make them more discoverable. Initially implemented as textual links to Edit this page for testing purposes, the links were later reduced to a pencil icon that is easy to overlook. We may want to publicize this new feature more widely.

Brief discussion on revising the top-level topic structure, questioning the usefulness of User Guide & Developer Reference as grouping mechanisms.

As suggested in the March docs call, it might be better to populate the top navigation level with more task-oriented groupings to make these topics more discoverable, rather than hiding them under the current “book” titles:

• Installing
• Building/Publishing
• Customizing/Extending/Plugins
• Troubleshooting

Since this change would affect the URL structure of the online docs, it would need to coincide with the next major release (3.0?), currently planned for November.

Additional suggestions are welcome, as we plan to revisit this issue during one of the next calls.

Backlog review

Currently 20 Open Issues, 51 Closed, no open PRs: https://github.com/dita-ot/docs/issues.

In #94, Radu proposes adding an FAQ section to the docs, and offers the content of his blog post as raw material. Discussion on whether to include this within the docs, or elsewhere on the project website. General consensus that it would be good to include in docs, perhaps under Getting Started. Some comments that FAQ format may not be necessarily be best. Others find the FAQ format helpful, so worth including as is for a quick improvement, can be refined later if we find a better format or location in the docs.

Issue prioritization

The main focus areas for the next few weeks will be extending the migration info provided for issue #29 with additional details, and adding more infomation on Customizing PDF output to augment the topics added for #70.

One related task that was de-scoped for 2.3 was to point out how the default structure facilitates diffs for complex plug-ins and add topics with file comparison examples, showing how to use GitHub history and 3-way diff & merge to see what's changed in recent plug-in releases.

For example, to see the history of changes in the pdf2 plug-in, visit: https://github.com/dita-ot/dita-ot/commits/develop/src/main/plugins/org.dita.pdf2.

Toward the end of the call, we decide to review the current backlog at https://github.com/dita-ot/docs/issues, assign priority tags (P1, P2, P3) to the list of open issues, and try to get a sense of the effort involved to implement the necessary changes for each issue, labeling each as small, medium or large (S, M, L).

We begin the process, but technical difficulties with the WebEx audio interrupt us several times, so we agree to continue during the next call. In the meantime, all members of the docs team are encouraged to review the list of open issues at https://github.com/dita-ot/docs/issues and add comments.

---