Documentation Platform/Tools Review
- Mike Gorrell
- Kelly Drake
Owned by Mike Gorrell
FOLIO requires User, SysOps, and Developer documentation. This page will serve as the collection spot for ideas and examples of documentation tools, processes and platforms. Eventually we'll document the official approach. Until that point this page serves as a collection and discussion spot.
Existing FOLIO-related documentation (as of May, 2019)
- FOLIO Developers -
- FOLIO App Information,Tips and Tricks - Confluence knowledge base space used to capture best practices and address common problems.
- Gap Analysis Videos - 2019
- Tools Documentation - documentation on connecting to the Library Reporting Database using various reporting applications
- System Administrators Guide - a list of documentation that a system administrator would need to be able to install/deploy, manage and update a FOLIO installation. It can also be called a best practices guide, or an administrator's guide, or an operations guide. The idea is to pull together existing documentation, identify the gaps, and write or request new documentation.
The Implementation SIG has had the following documentation related discussions:
- Recommend an environmental scan of existing open-source system documentation platforms
- Question if all types of documentation, User, SysOps and Developer need to be built on the same platform.
- For instance, Developer documentation might best be kept in GitHub, User in Confluence, etc.
- Believe the acceptable platform should:
- Pose a low barrier to entry
- Contain versioning system
- Allow for institution-specific forks
- Support multiple languages (although there is disagreement about whether the community would maintain the 'official' documentation in any language other than english)
- Agreed that ad-hoc documentation (until a platform is agreed upon) would be kept both in related slack channels and that users would also update the
Documentation should include:
- Why a decision was made
- When a decision was made