User Tools

Site Tools


evergreen-docs:reorg_2014:requirements

This is an old revision of the document!


Introduction

This document describes a proposed project to re-organize the official documentation of Evergreen. It is intended to spark discussion at a meeting in mid-February 2016.

Scope

Methodology

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

* A datetime in parentheses – e.g. (2015-02-19 13:10:04) – refers to a specific comment made at that time EST on the #evergreen IRC channel.

Ideas expressed about this project

Values

  • Documentation should be written for a "really defined audience" (2015-02-19 13:09:06), rather than a "grand mass of documentation" (2015-02-19 13:10:04) that tries to be "too many things to too many people" (2015-02-19 13:09:37).
  • This project should not interfere with DIG's ability to "keep up with docuemnting new features" (2016-01-20 14:26:51)

Goals

  • We would like to meet libraries' needs to have "essentially For Dummies books about each topical area" (2015-02-19 13:10:36)
  • 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" (2015-02-19 13:11:39)
  • Books that could be printed and used as "desk copies" (2015-02-19 13:14:34)
  • These books shouldn't be so individualized that DIG's work becomes much less easy to maintain (2015-02-19 13:17:14)
  • We would like an "automated solution" creating see also references that can jump between books (2015-02-19 13:19:38) and "that does not depend on a human to create the cross links for the HTML version" (2015-02-19 13:22:42)
  • Books should be presented separately, "but provide cross-search ability" (2015-02-19 13:23:51)
  • A procedure to "test the docs with our expected end users" (2015-02-19 13:31:17)
  • A plan to "convert that excitement into some actual commitment to assist with the (huge) project" (2016-01-20 14:17:25)
  • "Create the docs in small enough chunks so that they can be easily reorganized at any time." (2015-12-03 14:51)

Ideas

  • Separate books for "cataloging, circulation, acquisitions" (2016-01-20 14:54:19)
  • A separate book for consortial admins with shell access vs. local admins working through the staff client (2015-02-19 13:13:25)
  • Possibly a separate book for patrons (2016-01-20 14:56:11)
  • This project should leverage pre-existing open source solutions (2015-02-19 13:24:03), perhaps using some "AsciiDoc /Docbook magic to combine or seperate the output after being written" (2015-02-19 13:24:23) or flossmanuals (2015-02-19 13:36:51)
  • "if there are people with specific interests, they can be the initial compilers of the area documentation" (2016-01-20 14:21:33)
  • Possibility of using the Web Client Documentation to test the new organization (2016-01-20 14:32:57)
  • A "tag heirarchy could be implemented for each small chunk of documentation so you could remix them into the different types of organizing" (2015-12-03 14:52)
  • "The table of contents [should] always displayed to the left side of the screen (an expandable list showing the major topics and nested sub-topics) the user might be able to navigate the different parts of the document faster." http://markmail.org/thread/kjddts4zod2uwbe6
  • "The linearly organized information can be organized according to the knowledge level of the users." http://markmail.org/thread/kjddts4zod2uwbe6
  • "Creating a list of frequently asked questions for user reference" http://markmail.org/thread/kjddts4zod2uwbe6

Requirements

Interface requirements

PDF generation

Manageability and maintainability

Proposed timeline

  • February 2016: Decide on coordinators who are passionate about each audience
  • February 2016: Finalize the audiences
  • March 2016:
evergreen-docs/reorg_2014/requirements.1453738636.txt.gz · Last modified: 2016/01/25 11:17 by sandbergja

© 2008-2017 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.