Project Proposal: Update FOLIO End User and System Administrator Guides

About your organization

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 platform integrates the management of print and electronic resources; it includes functionality to manage the circulation of print materials, their cataloging and acquisitions, as well functionality to manage electronic resources including the library’s e-journal subscriptions or e-books. Yet FOLIO goes beyond ‘traditional’ library functionality. In order to drive continuous innovation, the platform leverages a microservices architecture. Rather than comprising a single, monolithic system, FOLIO supports smaller apps, so libraries can enjoy easier updates and benefit from faster development. Libraries can work on these apps independently or work with different vendors and different teams who may contribute and develop apps in their areas of expertise. The FOLIO APIs are thereby open, so the platform can integrate more easily with existing campus and library systems – providing libraries more choice for services today and in the future.

FOLIO is an open source project under the Open Library Foundation, a non-profit organization dedicated to open source in libraries. The FOLIO roadmap, requirements, discussions and code are all public. Community resources include:

• folio.org
• wiki.folio.org
• github.com/folio-org
• docs.folio.org
• dev.folio.org
• issues.folio.org
• discuss.folio.org

About the project

The FOLIO project needs to expand its supporting documentation for use by multiple types of librarians and system administrators.  Different librarians support different areas of library functions and each needs up-to-date information about how the FOLIO apps work in order to perform their day-to-day job functions. The site docs.folio.org is relatively new, and needs significant additional work in order to be a complete resource for users.  Currently, some apps have been documented and others have not. The first goal is to create a first version of documentation for each app.  As each first version for each app is created, we immediately need to shift to maintenance of that content so as not to fall out-of-date. 

For system administrators, we need additional documentation to explain how to install and maintain FOLIO in various types of institutional settings. This documentation will help both institutions who are investigating the possibility of implementing FOLIO as well as those who are already in the process of implementing FOLIO.

Ultimately, this documentation project is an important piece to support product adoption and general use.

Project scope

The Update FOLIO End User and System Administrator Guides project will:

• Create content for the apps that have no documentation available on docs.folio.org.
• Maintain the content that has already been published.
• Review the needs of system administrators to identify the most important content to develop.
• Develop the highest priority system administration documentation.
• Maintain the Installation content that has already been published.

We are currently looking for two technical writers for this project. See Technical Writer Qualifications below for more information. We estimate that the work will take six months to complete.  The writers will be supported by multiple SIGs, who have committed to making subject matter experts available.  The writers will also be supported by the FOLIO Technical Writing Editor, Marcia Borensztajn.

Measuring project success

We would consider the project successful if, after publication of the new documentation:

• There will be published content available for each of the FOLIO apps.
• The current documentation will be updated with changes based on the next releases.
• There will be published content available to support system administrators.

Project budget

Technical Writer Qualifications

We are looking for experienced technical writers with the ability to:

• Communicate complex ideas in writing in a simple, accessible way for a global audience
• Understand end user needs and build content accordingly
• Create content that meets established editorial standards
• Collaborate with subject matter experts across the globe

Nice to have:

• Background in library systems
• Knowledge of markdown language
• Familiarity with GitHub
• Graphic design skills

Interested technical writers should email samples of work to marcia1.folio@gmail.com. 

Additional information

Previous experience with technical writers or documentation:

As a technical writer/editor with over twenty-five years of experience, I have managed global teams of writers and mentored writers of varying degrees of experience. In the context of the Season of Docs program, I both reviewed the writers’ content myself and facilitated the connection between the writers and the appropriate subject matter experts.  They conducted their reviews both via Zoom and via shared Google docs.  Each of the writers brought a wealth of skills to bear on our project. Each was able to work effectively and efficiently with the relevant subject matter experts to clarify needs and resolve any open questions as they arose.

Previous participation in Season of Docs, Google Summer of Code or others: 

FOLIO first participated in Google Season of Docs in 2020 and continued on to participate in the 2021 season as well.  We originally worked with two technical writers, each of whom contributed significantly to the documentation effort. On the more technical side, one writer worked to create documentation of the installation process.  This content is of significant use both to institutions who are considering moving to our open source library platform, as well as to those who are already pursuing implementation.  Our other writer focused on librarians using the FOLIO platform in their day-to-day roles as librarians. With this content developed, the project is now able to better support end users as they perform their job-related tasks.  

-----------------------------------

-----------------------------------

Project Ideas 

After successful completion of the 2020 and 2021 Google’s Season of Docs initiative, the FOLIO community plans to participate in the 2022 program.  The Google Season of Docs program is an effort to bring technical writers and open source projects together to foster collaboration and improve documentation in the open source space. During the program, technical writers work closely with an open source community. They bring their technical writing expertise to the project’s documentation and learn about the open source project and new technologies.

As a community building an open source library services platform, the FOLIO community is inviting experienced technical writers to explore working with us to enhance our current documentation.  Below are the project ideas under consideration. We are happy to discuss adjustments to the projects based on the writer’s background and interests.

Project idea: Update FOLIO End User and System Administrator Guide

Problem

• Currently, there are some FOLIO apps that are not documented on docs.folio.org.  Our end users and community need documentation of all FOLIO apps in order to use the software effectively.  We also need to update the information to keep pace with the next releases of the software.  In addition, system administrators need more documentation to help manage the system.

How would we measure success

• There will be published content available for each of the FOLIO apps.
• The current documentation will be updated with changes based on the next releases.
• There will be published content available to support system administrators.

What skills would a technical writer need to work on this project?

• Ability to work with subject matter experts across the globe
• Ability to help define areas of priority
• Knowledge of library systems technical platforms
• Knowledge of the library industry

Project idea: Add graphics to the FOLIO End User and System Administrator Guide

Problem

• Our current documentation is text-heavy, and could be improved with the addition of graphics or short videos.  The graphics should be consistent and use the appropriate colors and branding.  To that end, some current graphics can be re-created to better align with FOLIO branding guidelines.

How would we measure success

• Add at least one graphic or video to each of the apps documented in docs.folio.org.
• Consistency among the graphics/videos.

What skills would a technical writer need to work on this project?

• Graphic design
• Video creation
• Instructional design
• Ability to work with subject matter experts across the globe
• Knowledge of the library industry

For more information about either of the FOLIO documentation projects, please contact marcia1.folio@gmail.com.