-
Notifications
You must be signed in to change notification settings - Fork 96
Meeting minutes 2016 01 07
- Adam Bukolt, HERE
- Alan Hegarty, TechLang Communications
- Georghios Skettos, HERE
- Juliane Groß, HERE
- Kavindra Palaraja, HERE
- Kristen James Eberlein, Eberlein Consulting
- Magda Caloian, PANTOPIX
- Nick Hill, HERE
- Roger W. Fienhold Sheen, infotexture
- Sebastien Quintas, HERE
- Shane Taylor, WebAssign
- Stefan Eike, DAKOSY
We begin with a round of introductions in which participants present their motivations for contributing to the project and particular areas of interest.
Kris & Roger thank participants for making the time to attend the call. Very pleased at the level of interest and glad to see so many people willing to contribute to the DITA-OT documentation.
Kris points out that the Eberlein Consulting WebEx account used to host the call only allows eight people to participate, so we were very fortunate that the team from HERE dialed in together, allowing four additional people to attend.
We're not sure if anyone else may have tried to join the call but was turned away after the call was full. If that becomes an issue, we'll investigate other hosting options for future calls.
Roger begins with an overview of the information available on the DITA-OT documentation project page at https://github.com/dita-ot/docs and explains the basic process we use to manage changes to the DITA-OT documentation.
Next we walk through some of the wiki pages that provide details on how we work, including the following:
Roger explains how the GitHub issues tracker at https://github.com/dita-ot/docs/issues is used to manage the documentation ToDo list.
We look at Update references to DITA 1.3 spec #48 as an example of the information associated with each issue, including:
- a label that categorizes the work
- a milestone that indicates the release version in which the issue will be resolved
- the person assigned to (or currently working on) the issue
- links to commits associated with the issue, and the changes they include
- a comment thread for discussion
Roger highlights the mechanism for associating commits with issues by including the issue number in the commit message.
(Kris says she is in regular contact with OASIS and expects the final DITA 1.3 spec URLs to be available any day now, so we should be able to update the docs with the final URLs and close #48 soon.)
Shane asks how to best represent subtasks within issues. Roger points out the GitHub checklist syntax - [ ] as used in Add Tutorials section #37, and the ability to link to other related issues by mentioning the issue number in the description or comments.
This leads to discussion on the main areas where input would be particularly welcome, as indicated by the help wanted label.
Kris relays feedback she has received from vendors that say many of the integration issues they have with clients are due to poorly implemented plugins and that the docs should include more basic information on creating plugins to override stylesheets & document type shells.
See Add Tutorials section #37 for a list of topics suggested so far, and add comments to suggest any additional topics you think might be useful — or let us know if you can contribute one of the suggested topics.
Sebastien asks how best to provide input on new topics such as best practices for plugin development. Roger suggests creating a GitHub issue and drafting an outline there, as the comment threads provide a good mechanism for discussion.
Roger points out that tutorials in the OT docs should maintain a clear focus on DITA-OT, as more general DITA best practices tutorials are beyond the scope of the OT docs.
Roger says the directory structure of the docs repository may soon be adjusted to better support continuous builds via Gradle. This shouldn't have any negative effects for other contributors, as long as all changes are isolated in a local feature branch.
Stefan suggests the docs could include more information on testing plugins. In his own plugin development, he's run into issues that could have been avoided if the docs had more info on this topic. This fits well with earlier discussion that suggests we need to improve our coverage of plugin-related topics in the docs. Any contributions in this area would be welcome.
Stefan suggests integrating a discussion tool in the docs on the project website to make it easier for readers to provide feedback. Roger responds that an Edit this page button has been proposed in dita-ot/dita-ot.github.io#8.
Kris suggests we may want to consider setting up a dedicated e-mail list for OT docs contributors. 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.
Participants in today's docs call should receive an invitation to join the Slack channel shortly.
Watch for a message in your Inbox titled:
Jarno Elovirta has invited you to join DITA-OT on Slack
Created 2016-01-07
View the latest DITA Open Toolkit docs at www.dita-ot.org/dev.