Differences

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

--- evergreen-docs:reorg_2014:requirements [2016/01/21 10:40] – [Requirements] sandbergja
+++ evergreen-docs:reorg_2014:requirements [2022/02/10 13:34] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
 ====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.
+===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===
+  * 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====
+===Values===
+  * 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 [[http://irc.evergreen-ils.org/evergreen/2016-01-20#i_223891|"keep up with docuemnting new features"]]
+===Goals===
+  * 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 [[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"]]
+  * [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157583|Books that could be printed and used as "desk copies"]]
+  * [[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 [[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"]]
+  * [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157612|Books should be presented separately, "but provide cross-search ability"]]
+  * [[http://irc.evergreen-ils.org/evergreen/2015-02-19#i_157632|A procedure to "test the docs with our expected end users"]]
+  * [[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"]]
+  * [[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===
+  * Separate books for [[http://irc.evergreen-ils.org/evergreen/2016-01-20#i_223963|"cataloging, circulation, acquisitions"]]
+  * [[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]]
+  * [[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), 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]]
+  * [[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 [[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]].
+  * [[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"]]
+  * [[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."]]
+  * [[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"]]
+----
 ====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.
+==Search==
+  * 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.
+===Testing===
+  * 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.
-====Risks====
+----
+====Proposed timeline====
+  * February 2016: Decide on coordinators who are passionate about each audience
+  * February 2016: Finalize the audiences
+  * March 2016: