FOLIO: Updating End User and System Administrator Guides
Organization Description: FOLIO is a community project for and by librarians and vendors alike to develop the FOLIO open source library management system or library services platform (LSP). FOLIO is an entirely new platform, designed by academic librarians, and written from the ground up as the first new LSP in 10 years. FOLIO seeks to provide libraries with more choice in how to develop, deploy and manage library software.
The FOLIO project uses apps to deliver functionality needed by libraries. There were many FOLIO apps that were not yet documented on docs.folio.org. Our end users and community need documentation of all the FOLIO apps in order to use the software effectively. We also wanted to improve our system administrator documentation.
Our original proposal discussed the need to create content for apps that were previously undocumented on docs.folio.org. It also discussed the need for updates to some existing content, including system administrator content.
Creating the proposal
The FOLIO project had worked successfully with the Google Season of Docs program during the 2020 season. Based on our very positive experience, it was clear that we would apply for the 2021 season.
The FOLIO community is active and engaged with all areas of the project. To advance the documentation of the software, feedback on the new proposal was solicited from members of FOLIO Special Interest Groups (SIGs), Marketing, Product Management, and the Documentation Manager (who also serves as the Google Season of Docs mentor for FOLIO).
We created a budget for two writers, and hired accordingly. Both writers returned to us from the previous 2020 season. However, after the project was underway, one of the two writers was unable to continue with the project due to unforeseen circumstances. Fortunately, our other Google Season of Docs writer was able to increase her contribution and make up for the shortfall. The project is expected to be on target in terms of the use of all the funds provided by the program.
The OpenCollective account was managed by the Open Library Foundation (OLF) Treasurer and the FOLIO Treasurer.
As stated previously, both of our writers had positive experiences with the program and expressed interest in returning for another season. Both writers created substantive relationships with people in our open source community and worked very well to create quality content.
Due to the extensive amount of end user content needed, the FOLIO project created a Documentation Working Group to manage various aspects of the production of content. The Working Group consisted of liaisons to FOLIO SIGs, so that there was effective communication between subject matter experts, the project mentor and the writers. In some cases, members of the Working Group drafted some content, while the writer clarified or re-wrote for style consistency. In some cases, the writer wrote from scratch and then worked with the appropriate subject matter experts (some of whom were the participants in the Working Group, and some who were not) to review the content for accuracy and completeness.
The goal of the project was to have all the end user apps documented by the end of the Google Season of Docs season (by the end of November, 2021). The vast majority of the apps now have completed documentation available and can move into maintenance mode.
As a result of the project, content was created for almost every end user app. While most of the content was created to support the Honeysuckle release of the software, some was created to support the subsequent Iris release. The content for the few Iris apps is set to be released in the near future. The docs for the Honeysuckle release can be found here.
Originally, the project was intended to include updates to some system administrator content. Due to unforeseen circumstances with one of our participants, that part of the Season of Docs project did not move forward. Instead, members of the FOLIO community worked on that content to update it as needed.
The shift away from the system administrator content as part of the Season of Docs project ultimately led the way to finish many more additional apps that still required documentation.
As a result of this project, most of the documentation is poised to be updated to reflect newer versions of the software.
The following metrics were used to measure the success of the project:
- There will be published content available for each of the FOLIO apps.
- There will be published content available to support system administrators.
Our metrics shifted once we understood that the writer originally tasked with working on the system administrator content would not be available. As a result, we were not able to work extensively on the system administrator content within the framework of the Season of Docs program. Instead, members of the FOLIO community worked on that content, while we focused on the remainder of the end user apps that needed documentation.
As the project evolved, it became clear that there was significantly more work needed to document all the end user apps. Even though we experienced a setback with one of our participants leaving the project, we were able to pivot and reallocate funds to make very significant progress with the other content that was needed.
Despite the setback in losing one participant, we consider the program to have been extremely successful. The writer remaining on the project was highly talented; both her writing and communication skills were excellent, and her work was a major reason for the project’s success.
Another reason for the project’s success was the availability of subject matter experts who invested their time and energy into the documentation. Working together with our writer, they made sure that the content produced was accurate and can meet the needs of FOLIO end users.
The 2021 Google Season of Docs program was a success for the FOLIO project. Extensive content was written and published, and it has received enthusiastic appreciation from users throughout the FOLIO community. While we now have an almost complete set of documents, our next challenge will be updating and maintaining that content as new releases of the software become available.
As other organizations seek to work with the Google Season of Docs program, it is important to be prepared to pivot as circumstances change and needs evolve. Another important factor is the availability of subject matter experts to work with the writers throughout the content creation process. The FOLIO project is fortunate to have many engaged community members who understand the importance of documentation, and were willing to help ensure successful completion of the documentation project.
The FOLIO project would like to thank all those involved in this program. We would like to thank both of our writers, the members of the extended FOLIO community who contributed their time and expertise, and the Google Season of Docs program for making this project possible.