(from 5-29-2019 SIG meeting)
--DRAFT--
Purpose
This document outlines needs for user management documentation in FOLIO, as defined by the User Management SIG.
These documentation needs may be met by the FOLIO Project, the FOLIO user community, or a combination of those resources.
Areas of Focus
Permissions
User permissions are managed through the Users App but have broad applicability across the FOLIO ecosystem. Documentation about user permissions should:
- List all available permissions and permission sets within the scope of that documentation, e.g., documentation for a specific app should outline all permissions and permissions sets available through that app, including UI and underlying modules
- Describe what an individual permission does, in language accessible to an end user of the FOLIO app (e.g., Library staff)
- Describe if/how a permission interacts with apps outside of the one where it is defined;
- Describe any dependencies a particular permission has, e.g. whether another permission is required for it to function, or it is required for another permission to function.
UX/UI
Documentation for the Users App UX/UI should
- List all available out of the box fields;
- Define the purpose of those fields;
- Define any data requirements for those fields, and where that data should be validated (in UI, underlying module, bulk loading, etc.)
- Define customization options for those fields (if any)
- List all available out of the box accordion menus;
- Define the purpose of those menus;
- Define customization options for those menus (if any)
Searching
Documentation on searching through the Users App should:
- Describe all pathways for searching user information through the FOLIO UI;
- Describe which fields are indexed specifically for searching;
- Describe any advanced searching features, including functionality and available fields.
Functional Processes
Several different types of functional library workflows live in the users app, including creating new patrons and fee/fine management.
Documentation for functional workflows in the Users app should:
- Describe all available functional tasks that can be conducted in the app;
- Describe all action-based permissions that are available for control of the functional workflow, including what that action-based permission does in language accessible to a FOLIO app user
- ...
Reporting
All libraries using FOLIO will expect to be able to run reports in the Users app and through the LDP to understand the work they are doing.
Documentation for reporting should:
Integrations
Many libraries (especially initial adopters of FOLIO) will need to integrate outside data sources with their users app, to add and delete users based on centralized identity management.
Documentation on integrations should:
- List all APIs that interact with the Users app and may be used in an integration workflow;
- Provide examples of common API calls (including code as relevant) to demonstrate how an integration works;
- .....
Types of Documentation
Different types of documentation will need to be prepared to support user management in FOLIO, including reference documentation, tutorials/getting started guides, and how-to instructions for library workflows.
We would expect technical reference documentation to be produced by FOLIO developers, but it's important to recognize that that documentation is not sufficient for supporting the broader community.
The Users app will need:
- Reference documentation (much of which is outlined above) to fully understand the function of the app;
- Tutorials / getting started guides for new staff users and new institutions, including how to support integrations with external data sources;
- How-to guides to support common workflows and tasks that library staff need to do within the app.