User Tools

Site Tools



This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
evergreen-docs:reorg_2014:requirements [2016/01/21 10:37]
sandbergja created
evergreen-docs:reorg_2014:requirements [2016/02/10 14:29] (current)
jpringle [Requirements]
Line 1: Line 1:
 ====Introduction==== ====Introduction====
-=====Scope=====+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 [[irc://​​Evergreen|#​evergreen IRC channel]] or the [[https://​​communicate/​mailing-lists/​|Evergreen mailing lists]].
 +====Ideas expressed about this project====
 +  * Documentation should be written for a [[http://​​evergreen/​2015-02-19#​i_157561|"​really defined audience"​]],​ rather than a [[http://​​evergreen/​2015-02-19#​i_157567|"​grand mass of documentation"​]] that tries to be [[http://​​evergreen/​2015-02-19#​i_157564|"​too many things to too many people"​]].
 +  * This project should not interfere with DIG's ability to [[http://​​evergreen/​2016-01-20#​i_223891|"​keep up with docuemnting new features"​]]
 +  * We would like to meet libraries'​ needs to have [[http://​​evergreen/​2015-02-19#​i_157570|"​essentially For Dummies books about each topical area"​]]
 +  * Individual books for different classes of end-user, with [[http://​​evergreen/​2015-02-19#​i_157573|"​each book tailored to the end user at the desk rather than to an admin user"​]]
 +  * [[http://​​evergreen/​2015-02-19#​i_157583|Books that could be printed and used as "desk copies"​]]
 +  * [[http://​​evergreen/​2015-02-19#​i_157588|These books shouldn'​t be so individualized that DIG's work becomes much less easy to maintain]]
 +  * We would like an [[http://​​evergreen/​2015-02-19#​i_157608|"​automated solution"​]] creating //see also// references that can jump between books and [[http://​​evergreen/​2015-02-19#​i_157608|"​that does not depend on a human to create the cross links for the HTML version"​]]
 +  * [[http://​​evergreen/​2015-02-19#​i_157612|Books should be presented separately, "but provide cross-search ability"​]]
 +  * [[http://​​evergreen/​2015-02-19#​i_157632|A procedure to "test the docs with our expected end users"​]]
 +  * [[http://​​evergreen/​2016-01-20#​i_223850|A plan to "​convert that excitement into some actual commitment to assist with the (huge) project"​]]
 +  * [[http://​​evergreen/​2015-12-03#​i_218270|"​Create the docs in small enough chunks so that they can be easily reorganized at any time."​]]
 +  * Separate books for [[http://​​evergreen/​2016-01-20#​i_223963|"​cataloging,​ circulation,​ acquisitions"​]]
 +  * [[http://​​evergreen/​2015-02-19#​i_157581|A separate book for consortial admins with shell access vs. local admins working through the staff client]]
 +  * [[http://​​evergreen/​2016-01-20#​i_223971|Possibly a separate book for patrons]]
 +  * This project should leverage pre-existing open source solutions), perhaps using some [[http://​​evergreen/​2015-02-19#​i_157616|"​AsciiDoc /Docbook magic to combine or seperate the output after being written"​]] (2015-02-19 13:24:23) or [[http://​​evergreen/​2015-02-19#​i_157648|flossmanuals]]
 +  * [[http://​​evergreen/​2016-01-20#​i_223870|"​if there are people with specific interests, they can be the initial compilers of the area documentation"​]]
 +  * Possibility of using the [[http://​​evergreen/​2016-01-20#​i_223914|Web Client Documentation to test the new organization]],​ if it doesn'​t [[http://​​evergreen/​2016-02-04#​i_227005|cause more trouble than it is worth]].
 +  * [[http://​​evergreen/​2015-12-03#​i_218274|A "tag heirarchy could be implemented for each small chunk of documentation so you could remix them into the different types of organizing"​]]
 +  * [[http://​​thread/​kjddts4zod2uwbe6|"​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://​​thread/​kjddts4zod2uwbe6|"​The linearly organized information can be organized according to the knowledge level of the users."​]]
 +  * [[http://​​thread/​kjddts4zod2uwbe6|"​Creating a list of frequently asked questions for user reference"​]]
 ====Requirements==== ====Requirements====
-=====Interface requirements===== 
 +[[evergreen-docs:​reorg_2014:​survey-questions | Survey Questions]]
 +===Structure requirements===
 +  * 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===
 +==PDF generation==
 +  * 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.
 +====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.1453390671.txt.gz · Last modified: 2016/01/21 10:37 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.