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:
- IDL acronym used, but never definedLynn and Blake COMPLETE!
- Simply add term to glossary (can use suggested definition on bug report)
- Docs use acronym TLD without defining it
- Add term to glossary (can use suggested definition on bug report)
- Also change first use of "TLD" to "Top Level Domain (TLD)"
- 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
-
- We may want to include tips about Managing Tabs in Google Chrome
-
- Update "Holds Management" section for web client
- Update "Address Alert" section for web client
- Give example for importing stat cats via Holdings Import Profile
- Record bucket search by item type
- Archive stat cats clarification
Pull Requests ready for review
Add Index Terms Throughout the Docs
Add Terms and Definitions to the Glossary
- Glossary Committed to Master. Please add any additional terms and definitions. UPDATED!!
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.6] Angular Providers Interface – could use some re-writing and new screenshots.
- [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
- [2.4] Acquisitions Lineitem Order Identifiers -MassLNC/SITKA
- Consider borrowing from SITKA's chapter on this subject
- [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
- [3.0] 3 Day Courtesy Notice by SMS stephengwills
-
- It would be nice to briefly document all the available Helper functions (see Reactor.pm)
Circulation Administration
Credit Card Processing
[2.12] Credit Processor Stripe Settings Permissions- Done- [2.10] Credit card receipts and privacy (May simply copy the release notes)
Installation / Upgrade / Build / Translation
Integration with other software
Other (or not categorized yet)
- Admin interfaces updated to Angular (probably just need new screenshots)
- [3.2] Switching workstation settings to user settings: see this email, this irc message, these release notes, and especially this email
- [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
-
- 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
-
- NOTE: This was a big change! It may be worth writing more about it, maybe in the developer docs section.
Booking
- [3.6] Booking Capture in Angular – just needs some updated screenshots
Cataloging
- Holdings Editor Defaults - especially around call number defaults
- [3.6] Manage Authorities angular version – some light updates and perhaps some screenshots would be helpful
- [3.6] MARC Batch Edit angular version – some light updates and perhaps some screenshots would be helpful
- [3.6] Preloaded Audio Icon and Search Format – should be added to this documentation. Also, that documentation should probably also be included in the cataloging area (maybe as an antora partial?).
- [3.4] New Cancel Edit Button In Record Merge Interface jweston
- [3.4] Staff Catalog Basket Export Option jweston
- [3.4] Display Codes in Physical Characteristics Wizard Drop-downs – might be worth a screenshot
- [3.3] Experimental Angular Staff Catalog
- MARC Import/Export (a.k.a. Vandelay):
- [3.3] (Bug #1716473) Hide fields in the holdings editor, rather than simply graying them out Beth W. In progress
- 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.1]
Track Record Merges <html><span style="color: green;font-weight: bold"> COMPLETE!– pushed to master, 3.2 and 3.3 - [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.11] Copy Alerts - Angela COMPLETE! will commit with 3.0 release- [2.10] Additional fixed fields
Circulation
Billing
Holds
- [3.6] Hopeless 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.6] Test notification method
- [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
* staff account password resets
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.6] Angular staff catalog is now the default – probably lots of implications for step-by-step procedures, screenshots, etc.
- [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)
Course Materials
- [3.6] Course Materials Module – this test plan may be helpful
Public catalog
- [3.4] Carousels
- NOTE: This contains info that should be added to other sections (e.g. Administration, OPAC Customization)
- Add this tip (from Jason Boyer via Evergreen General Discussion List) to the OPAC Customization section:
- Here is the format to specify those parameters:
[% PROCESS carousels args={width=5,animated=1} %]
- [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
- [3.6] Subtotals
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?)
- Wrong Cover Art, and what to do.
- Administration
- Local Administration
- Library Settings Overview Tables (update) jweston
- 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 Floydhttps://github.com/evergreen-library-system/Evergreen/pull/115
- Search Filter Groups
- 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
- Patrons
- Registration - Define any undefined fields and what they're used for
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.1622221242.txt.gz · Last modified: 2022/02/10 13:34 (external edit)