Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
evergreen-docs:reorg_2014:requirements [2016/01/25 11:41] – [Requirements] sandbergja | evergreen-docs:reorg_2014:requirements [2016/02/09 11:45] – [Ideas expressed about this project] adding links to IRC logs sandbergja |
---|
====Introduction==== | ====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. | 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. |
| |
===Scope=== | |
| |
===Methodology=== | ===Methodology=== |
===Conventions for this document=== | ===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 [[irc://irc.freenode.net/Evergreen|#evergreen IRC channel]]. | * A datetime in parentheses -- e.g. (2015-02-19 13:10:04) -- refers to a specific comment made at that time EST on the [[irc://irc.freenode.net/Evergreen|#evergreen IRC channel]]. |
| |
| |
====Ideas expressed about this project==== | ====Ideas expressed about this project==== |
===Values=== | ===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). | * Documentation should be written for a [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157561|"really defined audience"]], rather than a [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157567|"grand mass of documentation"]] that tries to be [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157564|"too many things to too many people"]]. |
* This project should not interfere with DIG's ability to "keep up with docuemnting new features" (2016-01-20 14:26:51) | * This project should not interfere with DIG's ability to [[http://irc.evergreen-ils.org/evergreen/2016-01-20#i_223891|"keep up with docuemnting new features"]] |
| |
| |
===Goals=== | ===Goals=== |
* We would like to meet libraries' needs to have "essentially For Dummies books about each topical area" (2015-02-19 13:10:36) | * We would like to meet libraries' needs to have [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157570|"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" (2015-02-19 13:11:39) | * Individual books for different classes of end-user, with [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157573|"each book tailored to the end user at the desk rather than to an admin user"]] |
* Books that could be printed and used as "desk copies" (2015-02-19 13:14:34) | * [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157583|Books that could be printed and used as "desk copies"]] |
* These books shouldn't be so individualized that DIG's work becomes much less easy to maintain (2015-02-19 13:17:14) | * [[http://irc.evergreen-ils.org/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 "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) | * We would like an [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157608|"automated solution"]] creating //see also// references that can jump between books and [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157608|"that does not depend on a human to create the cross links for the HTML version"]] |
* Books should be presented separately, "but provide cross-search ability" (2015-02-19 13:23:51) | * [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157612|Books should be presented separately, "but provide cross-search ability"]] |
* A procedure to "test the docs with our expected end users" (2015-02-19 13:31:17) | * [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157632|A procedure to "test the docs with our expected end users"]] |
* A plan to "convert that excitement into some actual commitment to assist with the (huge) project" (2016-01-20 14:17:25) | * [[http://irc.evergreen-ils.org/evergreen/2016-01-20#i_223850|A plan to "convert that excitement into some actual commitment to assist with the (huge) project"]] |
* "Create the docs in small enough chunks so that they can be easily reorganized at any time." (2015-12-03 14:51) | * [[http://irc.evergreen-ils.org/evergreen/2015-12-03#i_218270|"Create the docs in small enough chunks so that they can be easily reorganized at any time."]] |
| |
| |
| |
===Ideas=== | ===Ideas=== |
* Separate books for "cataloging, circulation, acquisitions" (2016-01-20 14:54:19) | * Separate books for [[http://irc.evergreen-ils.org/evergreen/2016-01-20#i_223963|"cataloging, circulation, acquisitions"]] |
* A separate book for consortial admins with shell access vs. local admins working through the staff client (2015-02-19 13:13:25) | * [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157581|A separate book for consortial admins with shell access vs. local admins working through the staff client]] |
* Possibly a separate book for patrons (2016-01-20 14:56:11) | * [[http://irc.evergreen-ils.org/evergreen/2016-01-20#i_223971|Possibly a separate book for patrons]] |
* 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) | * This project should leverage pre-existing open source solutions), perhaps using some [[http://irc.evergreen-ils.org/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://irc.evergreen-ils.org/evergreen/2015-02-19#i_157648|flossmanuals]] |
* "if there are people with specific interests, they can be the initial compilers of the area documentation" (2016-01-20 14:21:33) | * [[http://irc.evergreen-ils.org/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 Web Client Documentation to test the new organization (2016-01-20 14:32:57) | * Possibility of using the [[http://irc.evergreen-ils.org/evergreen/2016-01-20#i_223914|Web Client Documentation to test the new organization]], if it doesn't [[http://irc.evergreen-ils.org/evergreen/2016-02-04#i_227005|cause more trouble than it is worth]]. |
* 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) | * [[http://irc.evergreen-ils.org/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"]] |
* "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 | * [[http://markmail.org/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."]] |
* "The linearly organized information can be organized according to the knowledge level of the users." http://markmail.org/thread/kjddts4zod2uwbe6 | * [[http://markmail.org/thread/kjddts4zod2uwbe6|"The linearly organized information can be organized according to the knowledge level of the users."]] |
* "Creating a list of frequently asked questions for user reference" http://markmail.org/thread/kjddts4zod2uwbe6 | * [[http://markmail.org/thread/kjddts4zod2uwbe6|"Creating a list of frequently asked questions for user reference"]] |
| |
| |
| |
| ---- |
====Requirements==== | ====Requirements==== |
===Structure requirements=== | ===Structure requirements=== |
* 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 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. | * 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==== | ====Proposed timeline==== |
* February 2016: Decide on coordinators who are passionate about each audience | * February 2016: Decide on coordinators who are passionate about each audience |
* February 2016: Finalize the audiences | * February 2016: Finalize the audiences |
* March 2016: | * March 2016: |