Table of Contents
This document describes a proposed project to re-organize the official documentation of Evergreen. It is intended to spark discussion at a meeting on February 10, 2016.
I compiled a list of mentions of this project by searching in IRC and mailing list logs. I then categorized these into values, goals, and ideas on this wiki page.
I then created at least one concrete requirement based on each goal.
Conventions for this document
- Links in the Values, Goals, and Ideas sections refer to specific comments made on the #evergreen IRC channel or the Evergreen mailing lists.
Ideas expressed about this project
- Documentation should be written for a "really defined audience", rather than a "grand mass of documentation" that tries to be "too many things to too many people".
- This project should not interfere with DIG's ability to "keep up with docuemnting new features"
- We would like to meet libraries' needs to have "essentially For Dummies books about each topical area"
- Individual books for different classes of end-user, with "each book tailored to the end user at the desk rather than to an admin user"
- We would like an "automated solution" creating see also references that can jump between books and "that does not depend on a human to create the cross links for the HTML version"
- Separate books for "cataloging, circulation, acquisitions"
- This project should leverage pre-existing open source solutions), perhaps using some "AsciiDoc /Docbook magic to combine or seperate the output after being written" (2015-02-19 13:24:23) or flossmanuals
- Possibility of using the Web Client Documentation to test the new organization, if it doesn't cause more trouble than it is worth.
- The current documentation must be re-arranged into separate books, each of which must present content in its own specific order.
- The exact same content must be present in multiple books without needing to be updated separately (e.g. a chapter about the Evergreen community, or an introduction to the client interface)
- The HTML version needs to have crosslinks between related content in other books.
End-user interface requirements
- PDFs should be generated (of both individual chapters and complete books) at the same time HTML is generated.
- PDFs need to be attractive and easy to read when printed.
- Users must be able to easily scope their search to just the current book or all books
Manageability and maintainability
- We need to have specific people assigned to re-organizing content and writing any new content that is needed. These should preferably not be current DIG members, so that the demands of documenting new features don't interfere with the completion of this project.
- The documentation needs to be split into small chunks for easier maintainability.
- We need a separate server for the re-organized docs so that we can test our docs on end users without interrupting access to the current documentation.
- We need to identify a group of beta testers for each book that will test out each book in their day-to-day operations.
- February 2016: Decide on coordinators who are passionate about each audience
- February 2016: Finalize the audiences
- March 2016:
evergreen-docs/reorg_2014/requirements.txt · Last modified: 2022/02/10 13:34 by 127.0.0.1