-
Notifications
You must be signed in to change notification settings - Fork 8
Options for Managing Documentation
aeschylus edited this page Sep 12, 2018
·
9 revisions
We want to create a "good" documentation experience for each of the relevant audiences:
- Core Contributors - people writing the Mirador source code/architecture
- Plugin Developers - people developing plugins for other developers to use, or releasing their bespoke functionality to the community.
- Application Developers - people who use the external Mirador API, or use plugins
- Mirador "Installers" (dropping it in a wordpress page, etc.)
- Mirador end users - people actually clicking and zooming around who need to know what Mirador's features are and how they work
This is a lot to handle, and will require some prioritisation.
Core contributors need to know what every function does and its inputs and outputs, perhaps with links to relevant documentation or issues. Most of this can probably be handled by JSDoc, lint-enforced comments.
Plugin authors need to know:
- What version supports what?
- An overview of how the plugin system works
- A clear description of the API methods available to plugins (whether that be react lifecycle methods, redux events, Mirador API-provided events)
- Style and UI guidance or components or style classes
- How to publish and update their plugins
- How to test their plugins during development
- What are the available external events, functions, getters, etc. for the mirador library?
- Examples of common tasks linked directly from documentation
- Way to share examples easily (codepen or jsfiddle template, and some kind of index of examples people can link to)
- High-level guides for installing into an application or page and interacting with it, possibly youtube videos (how to install mirador in rails, drupal, webpage, react application, vanilla-js, etc.)
- Browser support
- How-to guide (and preferably a video) for installing on a webpage
- Some guide or section explaining where Mirador starts and ends (back-ends, containing applications, etc.), with some links to push them in the right direction for common questions.
- Same for desktop version if we end up maintaining that
- Browser support statement
There are a lot of different kinds of end-users as well, so the field is large here.
- What are the features and how do they work?
- Integrated help mode/guided tour with tooltips that can be turned on?
- Inline help?
- Potentially some help to achieve common goals in the software, based on community liason (manuscript users, image users, etc.)
- How do we keep hand-written documentation up-to-date or versioned?
- What tools should we use for hand-written documentation and how should it relate to the in-source JSDoc documentation?
- Ability to run components separately? (Storybook, etc.)