Technical documentation items from 'things that could be better' survey

Owned by Jenn Colt
Last updated: Jun 04, 2024
4 min read

  1. I am concerned about FOLIO developing into a vendor-supported SaaS solution that is only nominally open because it is too complex and resource intensive for libraries to host themselves

  2. We need to be better at helping organizations give development time, based on conversations at wolfcon. What will the cross council follow up to those discussions be?

  3. a clear, non-confusing, ‘outlined’ process for outside developers to work with FOLIO, how to get started picking a project, who to communicate with, where to begin (locations, steps, things to know, processes to know)

  4. a guide for following to make sure you are on the right track and fulfilling all development needs, including a clear set of guidelines for FOLIO development (like dropping the PR nonsense about developing in other languages, and have something that says folio as a tool prefers Java, but you CAN do X but it won’t be as good or as fast or as efficient’)

  5. a calendar or example timeline of how to arrange the important steps you need to accomplish, how to get each one signed off by a FOLIO admin or leader for that area, and then a set of guidelines for the end of the project - how do you complete the project? How do you know it’s finished? People to talk to, guidelines for what constitutes completion, etc.

  6. It's been a challenge on-boarding new members into the team. Lack of updated documentation and proceses makes it difficult for new members to come up to speed.

  7. More collaboration among teams can help learn from each other, especially when working on the same applications.

  8. Enhancing FOLIO's capabilities and quality can be achieved by establishing well-defined processes and procedures. This includes technical and functional requirements in creating new modules or features for integration into FOLIO.

  9. We need to do what it takes to have more developers from Academic Institutions contributing back to FOLIO. I.e. EBSCO can’t fund development at this pace forever.

  10. FOLIO needs to lower its threshold for new libraries to get involved. A reasonable expectation is that skilled DevOps should be able spin up a FOLIO installation without any major issues.

  11. The community could do better in helping new adopters get started in folio.  This especially applies to those who are self-hosted.

  12. Many libraries and institutions have produced scripts, tools, small programs that enhanced the functionality of their FOLIO installation. It would be a good idea to share these tools in a central place, where the other FOLIO users can find them.

  13. Continue to work on documentation. I know I visit the FOLIO status documentation page daily, it’s been so helpful to have that chart while setting up FOLIO. Continually add please!

  14. “N00b” documentation. A well-structured document that explains the various components and how they interact and in particular how to make them interact is kind of missing. Should include troubleshooting also

  15. Module documentation needs to be better. It is not clear how to set parameters in several modules. Error messages can be wildly misleading. The health api maybe should be more informative than “ok” or nothing.

  16. https://dev.folio.org/reference/api/ is very helpful, but e.g. mod-agreements is missing. A good, centralized location for API documentation makes it easier for technical troubleshooting as well as people trying to automate workflows with scripts. More generally: Documentation of FOLIO is fragmented over too many places. I feel like there should be some kind of "landing page" for documentation which links to secondary documentation. https://docs.folio.org already exists, but is more of a description of workflows and high level usage of frontend apps and i feel like there is a gap between "Dokumentation for Frontend users" and "Dokumentation for developers of a specific Module"; Technical users which have to have a broader few of the whole system.

  17. Documentation: The official Folio documentation technically describes for most areas the definitions, the permissions and the actions. This is a good reference, but often a good overview, "getting started" or tutorial section would be desirable. Some documentation is outdated or untested. Another thing the documentation is missing are troubleshooting docs. From the sysadmin view, the Installation section needs rework, and we should also add some hints about computing requirements, system management, troubleshooting and monitoring.

  18. Folio needs an installer. We personally are working on helm charts to make installation of Folio easier. The installation of Folio on a single server for small instances, testing or development purposes should not be this complicated as it is now. A web interface for managing tenants and upgrades and an infrastructure overview would make running Folio much easier.

  19. I've heard that, for example, the Stripes documentation is insufficient or it's difficult to keep up to date on current developments or technical decisions.

  20. Overall, the documentation for FOLIO is pretty good, but as someone fairly new to the system, it's still often difficult to find what I need. A large part of this is that the documentation is split between several locations (http://dev.folio.org , http://wiki.folio.org , GitHub), which often don't agree with each other. The http://dev.folio.org search helps a lot with finding information, but is still often insufficient.

  21. From a developer standpoint, I really wish local development was simpler. The vagrant VM seems useful, but only if you have a TON of RAM to actually run it. It's easy to point a locally running module at a shared environment, but it gets tricky if you want to run more than one module and have them interact with each other. Related to that: the dev/shared environments (rancher, snapshot, etc) would be significantly more useful if remote debugging was enabled by default, as this would remove a lot of the need for local development.

  22. Create and maintain thorough and up-to-date documentation for both developers and users, encompassing detailed user guides, technical specifications, and best practices for each module. This documentation should be organized in a centralized location with an effective search function, enabling users to efficiently navigate and locate relevant information. By providing a comprehensive knowledge base, the FOLIO community can more seamlessly support the successful implementation and operation of the system across various libraries and institutions.

  23. We need a process for clear, well-structured and searchable documentation that is maintained sustainably.