| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| evergreen-docs:reorg_2014:requirements [2016/01/25 11:41] – [Introduction] sandbergja | evergreen-docs:reorg_2014:requirements [2022/02/10 13:34] (current) – external edit 127.0.0.1 |
|---|
| ====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. |
| |
| ===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]]. | * Links in the Values, Goals, and Ideas sections refer to specific comments made on the [[irc://irc.freenode.net/Evergreen|#evergreen IRC channel]] or the [[https://evergreen-ils.org/communicate/mailing-lists/|Evergreen mailing lists]]. |
| |
| |
| ====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==== |
| | |
| | [[evergreen-docs:reorg_2014:survey-questions | Survey Questions]] |
| ===Structure requirements=== | ===Structure requirements=== |
| * The current documentation must be re-arranged into separate books, each of which must present content in its own specific order. | * The current documentation must be re-arranged into separate books, each of which must present content in its own specific order. |
| * 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: |
