evergreen-docs:documentation_needs
This is an old revision of the document!
Table of Contents
Evergreen Documentation Needs
High level workflow for documenting new EG features
| 1. Choose a Task | 2. Read Release Notes | 3. Update the Docs |
|---|---|---|
| - Look at the task list below and add your name next to a task - Need a wiki account? Just ask. | - Review the release notes entry for the feature (and/or the Launchpad bug) - It may need a new section in one or more of the official manuals - It may fit within an existing section - It may only need updated screenshots - You may be able to simply copy the release note into the appropriate section | - Make corrections in any format (perhaps by editing on GitHub) and share with the email list - Learn more about ways to contribute your changes |
Style Guide
- Remember to follow (and improve) the DIG Style Guide
EASY Tasks for New Contributors
Bitesize (simple) documentation bugs on Launchpad:
- Documentation needed for adjustable font size in the catalog
- To fix this, let's add a section about browser font size controls to the "Using the Browser Staff Client" chapter
- Add tips for using the browser bookmarks toolbar in place of the XUL button bar
- Update "Holds Management" section for web client
- Update "Address Alert" section for web client
Pull Requests ready for review (according to Launchpad):
- Replace screenshots in "Circulating Items" chapter
- "Delete record" option missing from OPAC view
- Possible places to link to the new section:
Add Index Terms Throughout the Docs
Add Terms and Definitions to the Glossary
Documentation Re-Organization Clean Up Tasks
- Help improve the various new documentation manuals
Other Documentation Tasks
- All documentation bugs on Launchpad
TIPS
Check Sitka's documentation, especially when documenting older features: Also, consider adding links to their YouTube videos.Quick Start Guides
We would like to provide an "Evergreen Quick Start" guide for the most common functions of Evergreen. The intended audience is library volunteers, student workers, and staff who are new to libraries. Learn more about the initial idea.
- Some key features of such a guide would be:
- Short (hopefully fitting on a single page printout)
- Simple (no library jargon, no extra explanations)
- Generic (not specific to any library or consortium)
- Includes a short video
- See Sitka's short videos for examples.
Here's a list of the guides we think we need. Feel free to add more!
Check In
Check Out
- See the draft of a video script.
Adding Holdings
Adding call numbers and items to a bibliographic record.
- How would you say "bibliographic record" without library jargon?
Undocumented Features/Changes, Taken From Release Notes
Many of these will be easy changes. Some will need no changes at all.
Copy the HTML code below to update the status of an item:
- Assign yourself:
<html><span style="color:blue;font-weight:bold">[your name]</span></html>([your name]) - Add a status:
<html><span style="color: green;font-weight: bold"> COMPLETE!</span></html>(COMPLETE!)
Acquisitions
- [3.2] Invoice Closed Date and Closed By Fields – it would be helpful to document the advice about creating report templates here
- [2.4] Acquisitions Inline Item Detail View -MassLNC/SITKA
- Consider borrowing from SITKA's chapter on this subject
(old link)
- [2.4] Acquisitions Lineitem Order Identifiers -MassLNC/SITKA
- Consider borrowing from SITKA's chapter on this subject (old link)
- [2.4] Acquisitions Purchase Order and other Interface Improvements -MassLNC/SITKA
Administration
Acquisitions Administration
- [3.2] New acq admin interfaces (listed under Architecture > Angular6 Base Application), probably needs screenshots
- [3.0] New EDI Order Generator
Notification / Action Triggers
-
- It would be nice to briefly document all the available Helper functions (see Reactor.pm)
Circulation Administration
Credit Card Processing
- [2.10] Credit card receipts and privacy (May simply copy the release notes)
Installation / Upgrade / Build / Translation
Other (or not categorized yet)
- [3.1] New Latency Tester Tool
- [3.0] Configurable Bib Record Display Fields – this would be helpful with an example of how to display these fields in notification templates and/or elsewhere
- [3.0]
Fix COPY_STATUS_LONGOVERDUE.override Permission Typokatiegmartin correct in circulating_items_web_client.adoc -
- START WITH: [2.12] Batch Hold Targeter Speed-up and New Features (just copy the release notes entry to the docs)
- [2.10] sortable HTML reports
- EASY: Update screenshot of report output: http://docs.evergreen-ils.org/3.1/viewing_report_output.html
- EASY: Add brief statement somewhere on that page: "HTML reports can be sorted by clicking on the header for a given column. Clicking on the header toggles between sorting the column in ascending and descending order. NOTE: Sorting is available only when there are at most 10,000 rows of output."
- [2.10] Some documentation may need to be updated based on these changes
API
Architecture
- [3.1]
Sample Data Includes Surveys– added to the wiki page about concerto data: https://wiki.evergreen-ils.org/doku.php?id=qa:concerto_logins -
- NOTE: This was a big change! It may be worth writing more about it, maybe in the developer docs section.
Cataloging
- MARC Import/Export (a.k.a. Vandelay):
- [3.3] (Bug #1716473) Hide fields in the holdings editor, rather than simply graying them out
- Spine Labels:
- [3.0] Printing spine labels (see bug #1704873) - Some very basic documentation exists, but it needs more content about how to work with the templates, etc.
[3.2] Support for Last Inventory Date <html><span style="color: green;font-weight: bold">COMPLETE!</span></html> Pull request 82- [3.0] Include Call Number Prefixes and Suffixes in Export and Z39.50 output – added to Export documentation, not yet in Z39.50 documentation
[2.12] New Access Points for MARC Merge/Overlay Profiles - GitHub PR #72[2.11] Copy Alerts - Angela COMPLETE! will commit with 3.0 release- [2.10] Additional fixed fields
- [2.10]
Link personal name/title series added entries- COMPLETE and pushed to 3.1 and above
Circulation
Billing
Holds
- [2.5] Wrong-Shelf Holds in Clearable Shelf-Expired Holds List - Should be incorporated (with updated screenshots) in newly revived Holds documentation
Patrons
- [3.3] (Bug #1490616) Changed "Staff-Generated Penalties/Messages" label to "Penalties and Messages" in patron display form
- Simple text changes
- Needs updated screenshots
-
- NOTE: Seems to be finished in 3.0 manuals
- CONSIDER removing earlier draft section: XI. User buckets
- [3.0]
Patron Search by Birth Date: Katie - [3.0]
Retrieve Recent PatronsKatie
Self Check Out
Other (or not categorized yet)
-
- CAREFUL: This intentionally replaces a "new" feature from 3.0.1: https://bugs.launchpad.net/evergreen/+bug/1719967
- [2.5] User Setting Defaults
Client
- [3.2] Browser Client Settings & Preferences Stored on the Server – also see this IRC discussion: http://irc.evergreen-ils.org/evergreen/2019-06-03#i_408119
- [3.0] New "About Evergreen" page (see bug #1718036)
Public catalog
- [3.1] Search term highlighting
- [3.1] Multi-source Attributes
- [3.0] jQuery for the TPAC
-
- NOTE: It looks like this should be documented under Designing your catalog
- [2.12] Metarecord Search Improvements [Kathy] In Progress - Note: The net effect of these search improvements was to fix bugs where we couldn't limit by format, properly retrieve e-resources, or navigate metarecord search results correctly. Since those bugs weren't mentioned in docs, I don't think anything new needs to be added here. It just works in places that it didn't work before.
- [2.12] RDA Improvements
-
- EASY: Add release notes to TPAC docs within section "Adding and removing MARC fields from the record details display page"
- [2.5] Conjoined items - update [[http://docs.evergreen-ils.org/2.4/_conjoined_items.html docs to update with tpac functionality and replace jspac screenshots with tpac screenshots.]]
Reports
SIP
- [2.5] Return Hold ID to SIP - Probably requires some documentation since the use cases it support may not be immediately apparent. (the release notes are not clear about when this is returned, etc.)
Borrow from Shared Docs
- Web Client docs
- Shared by Katie Greenleaf Martin (Blair County Library System)
- NOTE: Only use the files showing the CC BY SA 4 logo, or ask Katie to ask the authors
- Shared by Diane Disbro (Scenic Regional Library)
- Only "Circulation Training Manual" volumes 1 & 2 are updated for the web client so far.
- Command Line installation demos (Evergreen 2.12, includes web client)
- Shared by Ben Shum (Evergreener.net)
- Inventory
- Elaine Hardy of PINES wrote some instructions that can be adapted into the official docs.
- Patron penalty color-codes (colored border around patron name) (see Bug 1759357)
Other Requested Documentation
- Cataloging (needs to be reorganized)
- Need a new "Volume/Copy Editor" section (borrow from "Monograph Parts")
- Intro to SQL (Based on Dan Scott content) Yamil still needs to make some edits like proper attribution, and test that its addition does not break the full docs
Library Settings Editor- (Lynn Floyd, SCLENDS)- OpenSRF/Evergreen Installation Guide (two PDFs linked from email below, useful but need updating)
- Archiving of Circulation Transactions (new section)
- Addresses on Routing List (missing?)
- Administration
- Local Administration
- Copy Template Editor
- Field Documentation
- Group Penalty Thresholds
- Hold Policies - some very useful info here (especially from a command-line perspective): https://evergreen-ils.org/~bshum/eg12/looking-glass/notes.html
- Patrons with Negative Balances Lynn Floyd
- Search Filter Groups
- Surveys Lynn Floyd
- Transit List Lynn Floyd
- Hold Targeting and Hold Targeting script
- Acquisitions
- Patron Requests/Acquisition requests - Notes Gist
- Server Administration
- Actor Stat Cat Sip Fields
- Age Hold Protect Rules
- Asset Stat Cat Sip Fields
- Billing Types
- Circulation Matchpoint Weights - use wiki page
- Custom Org Unit Trees
- Global Flags
- Hold Matchpoint Weights
- User Setting Types [Stompro]
- Database Backup and Restore Documentation Notes/In Progress Gist
- Loop-Based Hold Targeting & Pickup Location Weight Notes/In Progress Gist
- Override Permissions - need docs that explain that any event can have an override permission created.
- Z39.50 server setup - DBS docs on setting up Z39.50 Server
- Circulation
- Hold Design - There doesn't seem to be anything that describes how holds work in the current documentation.
- A great start in the wiki by phasefx - http://wiki.evergreen-ils.org/doku.php?id=scratchpad:holds
- There is a presentation by Equinox - http://evergreen-ils.org/~corinne/Hippos_Final.ppt
Non-Docs Tasks
- Incorporate relevant docs links into Web Staff Client screens (i.e. contextual help)
- Improve docs testing/building via the automated testing server (aka buildbot)
- Currently, the docs are built (HTML, PDF and ePub) whenever the tests are run (every day around 6am and 6pm EST). If there is any warning or error output, it should signal a failure of the tests.
- Ideas to improve this include:
- Adding spellcheck (using the aspell wordlist)
- Checking for other common mistakes (incorrect image references, unused image files, etc.)
- Improve the PDF version of the built documentation (ask community for usage, ideas, etc.)
- Setup/use Google analytics to improve docs website design
- UI improvements
evergreen-docs/documentation_needs.1559851420.txt.gz · Last modified: 2022/02/10 13:34 (external edit)