Skip to content

Meeting minutes 2017 01 05

Jump to bottom Edit New page
Roger Sheen edited this page Jan 5, 2017 · 1 revision

DITA-OT Docs Call — January 05, 2017

Contents

Attendance

  • Dawn
  • Jarno
  • Kris
  • Peter
  • 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-2017-01-05.

2 new maintenance versions of DITA-OT have been released since the last call:

New issues since last call

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

Fixed issues since last call

A total of 5 issues & pull requests were closed.

Of those, 2 were pull requests by Lionel Moi and Eero Helenius:

Project planning board review

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

Issue Discussion

Add a Description of Dublin Core Outputs #125

  • Jarno mentions that the current mappings have never changed
  • Suggests we might want to add a parameter that toggles that metadata generation on/off between formats, i.e. DC, schema.org and/or custom fields
  • Not to be confused with accessibility attributes
  • Primarily an SEO feature

Update site search #35

There are several proposals to replace the search mechanism on the project website with something that would provide a better user experience:

  1. Algolia DocSearch

    On December 1, 2016, Stephan suggested in the #documentation channel on Slack:

    There is a free service called docsearch from a company called Algolia. You can use the service to get a small search box for searching the docs. Similar to what the DITA-OT docs does with DuckDuckGo, but more beautiful, because you don't have to leave the site.

    You can see an example on https://facebook.github.io/react/.

  2. WebAssign custom search

    Later in that discussion, Shane offered a custom solution he implemented for his employer, which considers DITA-specific criteria such as where terms appear title, shortdesc, index terms, etc.

    Re docs search, I wrote a DITA-aware indexer and search for our helps a couple years ago; it's been working pretty well in our helps (see http://www.webassign.net/manual/instructor_guide).

    Happy to talk with my company about contributing it […]. It has stemming and synonym support, and you can easily add synonyms and tweak the weighting of things like titles, indexterms, and short descriptions

The plan is to test the Algolia DocSearch solution first, and if Shane is able to contribute his solution, we can evaluate that in a separate pull request.

Revise top-level documentation structure #121

Kris comments her approach as an IA would be informed by her tenure @ IBM, would usually begin by agreeing on a short list of top-level topics, assigning current topics to those.

Focus on task-based approach for most things, which can sometimes raise the issue of what to do with reference material, but with good related links, any potential negative effects of a separate top-level reference section can be mitigated, as users are directed from task-based material toward relevant reference content.

Peter raises the point that a multi-faceted approach should consider not only a single static hierarchy, but multiple entry points and ways of reaching information.

Jarno's would prefer that the Parameter Reference should still be available on the top-level.

Shane suggests that people actually need reference material in the context of what they're trying to do (how can I customize HTML5), so it may be better located there, rather than as a separate section.

Peter: why not do both?

Dawn echoes this idea: devise a publication structure that provides both dedicated reference sections and includes relevant reference materials in the context of each user task.

How to move forward?

  • Shane to prepare spreadsheet as the basis for a content inventory (per our December call)
  • Kris to take a first pass at category suggestions

Index the topics #53

Peter has reviewed guidelines for indexing, wonders where to best summarize his findings.

Roger points to the project wiki as the central location for information on documentation process.

  • Peter to create wiki page for indexing resources
  • Roger to enable index in dev PDF output

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

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

DITA-OT Docs Wiki

Clone this wiki locally