FOLIO Documentation

For questions regarding documentation, please contact Marcia Borensztajn (Documentation Editor).

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

Documentation Contribution Guidelines

FOLIO documentation consists of the following repositories and sites:

• https://docs.folio.org: This site is primarily for end user documentation. It is accessible via folio.org, and will soon be available via a Help icon in the FOLIO user interface.  The site is built using Hugo, an open source static site generator. The theme used for the Hugo site is an open source theme called Docsy.  Much adaptation was done to the theme for branding purposes and to improve usability.
• https://github.com/folio-org/docs: This repository provides version control for all of the content housed on docs.folio.org.
• https://issues.folio.org/secure/Dashboard.jspa: This site provides for workflow management of items related to documentation.
• https://wiki.folio.org/display/SS/FOLIO+Documentation: This page provides updates regarding progress in building out the tools and processes needed to support documentation functions.

Please see the FOLIO Individual Apps: Information, Tips and Tricks for community created documentation. 

Contribution Mechanisms

Currently there are two mechanisms by which to contribute to the documentation:

The first is to work with the relevant members of the FOLIO community to draft and review content.  The following roles are involved:

Documentation Editor/Manager: Responsible for content creation, including organization of content, consistency of writing approach, and adherence to the selected style guide.  Responsible for many of the technical aspects of creating and maintaining the docs.folio site (including adaptation of the template for branding and usability, and not including hosting aspects). Responsible for managing the process of content creation, working with community members to iterate on drafts until finalization and publication. Responsible for ongoing maintenance of content to ensure accuracy as new versions are released.  Role currently performed by Marcia Borensztajn.

Documentation Working Group Members: Members of the group are responsible for ensuring that content is written and reviewed by Subject Matter Experts from relevant Special Interest Groups (SIG). In some cases, the working group members write content, and in other cases, they work with the Editor or a Writer to inform and review content. 

Product Council Liaison: member appointed to provide guidance and advocate on behalf of the Documentation Working Group to the PC, broader community as appropriate. Support the Documentation Editor/Manager by collaboratively developing agenda, sending out the monthly agenda, meeting reminders, and taking notes.

Meetings -  The second Wednesday of the month , 10a-11a EST/16-17p CEST. 

Zoom meeting info- https://openlibraryfoundation.zoom.us/j/89637604553?pwd=YXhHTTMyVjJiZWtwQkIwQlNxKzRiUT09

Meeting ID: 896 3760 4553
Passcode: folio-lsp

Subject Matter Experts: In some cases, Subject Matter Experts are responsible for writing content, and in other cases they inform and review content.  Subject Matter Experts are asked to review content based on the recommendations of the Documentation Working Group.

Google Season of Docs Writers: Google Season of Docs writers work with Subject Matter Experts and the Documentation Editor to create content.  Our Google Season of Docs writers have each returned to work with the FOLIO project for their second round of the program.  The writers are Lauren Gallina and José Ortiz.

Interns: The FOLIO project had the benefit of working with three interns from Missouri State University.  These interns helped write content for the Finance, Invoices, and Receiving apps.  The project is also working with a student at San Jose State University to produce some initial instructional design content.

Technical Support Personnel: Responsible for technical support for the documentation site, the documentation GitHub repository, and the JIRA documentation project.  Role currently performed by Peter Murray.

The current mechanism for collaboration on content creation is via Google docs.  The shared Google drive that holds all drafts is located here: https://drive.google.com/drive/u/1/folders/1_Y1ukJOJweyUEvnecNyKt3lcAvCO-Rsm

Once content has been finalized, the content must be converted to markdown language and pushed to GitHub.  The Documentation Editor creates a branch on GitHub to hold the working files needed.  Next, the content is converted into markdown format.  This conversion is currently done via a Google docs to Markdown browser extension.  Once the initial conversion is done, manual cleanup of the content is necessary to fix bolding issues and to manually add links to other topics within the docs.folio site.  When the files are ready, the Documentation Editor creates a pull request and merges the changes into the GitHub repository. Once the changes are merged, the updated content is reflected on the live site.

The second mechanism to contribute to FOLIO documentation (outside of working with Google doc drafts) is to submit changes directly via pull requests in GitHub.  Currently, this avenue is used primarily by technical users in the FOLIO community who are submitting changes to installation procedures.

Content Standards

When developing content, the topic must be structured in a manner consistent with the current documentation.  Topics that describe app functionality must include an introductory statement, a list of related permissions, and definitions that are relevant to the particular app. Within a topic, the description of creating, for example, a "new" invoice/course/etc. comes before a description of "searching and filtering" for relevant content.  It is then followed by a description of viewing displayed information. 

Topic contents are also structured in relation to how they appear in the user interface.  Within each topic, it is necessary to notice when subsections are used vs. bulleted lists of field descriptions.  It is important to use current topics as a model for any future topics written.

The style guide selected for the project is the Google Developer Style Guide.  Note that the style guide calls for the use of simple, direct language to enable non-native English speakers to be able to understand the content.  The use of simple language also paves the way for future localization efforts.  Accessibility guidelines should also be considered carefully.

Beyond these considerations, the guide recommends overall best practices, including avoiding multiple levels of nested bullets/numbered steps or the use of passive tense.  Attention must be paid to style and grammar, including but not limited to consistent capitalization, bolding conventions, and order of directions for numbered procedures.  Given that the documentation has multiple authors, each with their own general style and approach, it is critical to re-work materials until a consistent voice is achieved.

Consistent terminology is also key to the usability of the FOLIO documentation. It is important that the terminology used in the user interface is accurately reflected in the documentation to create a seamless user experience.

Issue Management

JIRA is currently used to manage documentation issues in several ways.  First, it is the chosen mechanism to log either bugs in the documentation or enhancements that need to be considered for existing documentation. Anyone on the project can log an issue for consideration. The documentation project appears as follows:

The documentation dashboard appears as follows:

Ideally, when a new story is written in JIRA, the product owner or their designee is responsible to consider the impact on documentation.  Existing documentation may need to be updated, or new documentation created to address the changes described in the story.  The story item in JIRA should be “related to” a parallel item opened in the documentation project in JIRA.  This process is just beginning to take place and needs to be more thoroughly embedded into the FOLIO community development processes.

Currently, some updates that are relevant for a particular release have the release name in parenthesis in the title of the JIRA item.  More work needs to be done improve how JIRA is used to track items intended for a specific release.  Additionally, more work needs to be done to use JIRA to effectively manage items through the documentation workflow.

Version Management

GitHub tracks the different versions of each piece of content.  However, to manage documentation in supporting different releases of FOLIO, more work is needed.  The theme used in the docs.folio Hugo implementation (Docsy) can be configured to enable a drop-down list of releases (Honeysuckle, Iris, etc.).  This work has been started and is being stored on a separate branch until such time that content for Iris is ready.

Localization

Internationalization of the Hugo-based docs.folio site has been completed in 2020. Work on German localization (= actual translation) has been started, and is being stored on a separate branch (Branch/Pull Request, Preview) until such time that content is ready for inclusion and gets approved by the German translation team.

Context-sensitive Help

Future work should include a mechanism for users to click on an area of the user interface and open the relevant section of the documentation for help.

Current Status of Content

The following table lists each area, the associated SIG, and the current state of the documentation.

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

January 7, 2021

Phase 2 is complete.  Advances include:

• Enabled access to the live site from folio.org
• Established presence in JIRA for documentation
• Refined drafts of Resource Access content
• Created draft of content for the new Circulation Log app
• Refined drafts of Installation content

Next steps:

• Enable access to docs.folio.org/docs from the UI
• Conduct final review of Resource Access content (Check in, Check out, Reserves, Courses, and Circulation Log)
• Conduct final review of Installation content
• Begin documentation of Orders, Finance, Invoices, and Receiving apps
• Create version control strategy for older versions of FOLIO documentation
• Work with POs and others to use JIRA for maintenance of published content

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

October 29, 2020

Highlights of recent advances include:

• Published initial site: see https://docs.folio.org
• Established documentation version control using GitHub: see https://github.com/folio-org/docs
• Selected Google Developer Style Guide: see https://developers.google.com/style

DRAFT content created:

• Google Season of Docs writer (José Ortiz): drafted content for Getting Started and Installation
• Google Season of Docs writer (Lauren Gallina): drafted content for Check in, Courses, Reserves
• Drafted content for Home, About, Features, Benefits, License
• Drafted content for Check out

Next steps:

• Lay groundwork for accessing the site from folio.org and the UI
• Create strategy for effective use of JIRA to track and manage documentation work
• Address additional technical issues
• Establish roles for documentation review
• Refine current content; review with subject matter experts

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

October 12, 2020

FOLIO documentation efforts are underway.  See the Information Plan for details of each phase.

Phase 1 of the plan is complete. Highlights include:

• Creation of a demo documentation site
• Creation of high-level content structure (TOC)
• Creation of initial draft for Check out / Check in apps
• Onboarding of Google Season of Docs technical writers

In Phase 2, the first items to address are:

• Moving the demo site to an accessible location
• Establishing a docs repository on the FOLIO GitHub site 
• Improving initial draft content
• Selecting the next areas to document
• Documenting some FOLIO installation options

Phase 2 will be complete in the mid-end November timeframe.