Page tree
Skip to end of metadata
Go to start of metadata

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

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

Documentation Contribution Guidelines

FOLIO documentation consists of the following repositories and sites:

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

Area

Working Group Representative

Home/About

N/A

Getting Started

N/A

Gettings Started -> Installation

Ingolf Kuss

Get to know FOLIO

Hope Sagnip
Platform EssentialsErin Nettifee, Julie Brannon

Users

Christine Tobias

Bulk editTBD

RA/Circulation > Check out

Erin Nettifee

RA/Circulation > Check in

Erin Nettifee

RA/Circulation > Circulation Log

Erin Nettifee

RA/Circulation > Requests

Erin Nettifee

RA/Circulation > Courses

Erin Nettifee

RM/Acquisitions > Orders

Julie Brannon

RM/Acquisitions > Finance

Julie Brannon

RM/Acquisitions > Invoices

Julie Brannon

RM/Acquisitions > Receiving

Julie Brannon

RM/Acquisitions > Organizations

Julie Brannon

MM/Cataloging > Inventory

Laura Daniels

MM/Cataloging > MARCauthority

Laura Daniels

MM/Cataloging > Data export

Dennis Christman

MM/Cataloging > Data import

Dennis Christman

ERM > Agreements

Emma Raub

ERM > Licenses

Emma Raub

ERM > eHoldings

Emma Raub

ERM > eUsage

Annika Schroer

Dashboard
ReportingAxel Dörrer, Sharon Beltaine

Settings

(Multiple)

Glossary

(Multiple)

Liaison to Product CouncilDracine Hodges

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.

Area

Associated SIG

Status

Home/About

N/A

Published.

Getting Started

N/A

Published.

Gettings Started -> Installation

SysOps

Published as draft. Pending final signoff on certain sections.

Get to know FOLIO

N/A

Draft in progress.

Platform EssentialsMultiplePublished.

Users

User Management

Published.

Check out

Resource Access

Published. 

Check in

Resource Access

Published.

Circulation Log

Resource Access

Published.

Requests

Resource Access

Published.

Courses

Resource Access

Published.

Orders

Resource Management

Published.

Finance

Resource Management

Published.

Invoices

Resource Management

Published.

Receiving

Resource Management

Published.

Organizations

Resource Management

Published.

Inventory

Metadata Management

Published.

MARCauthority

Metadata Management

Published.

Data export

Metadata Management

Published.

Data import

Metadata Management

Published.

Agreements

Resource Management

Published.

Licenses

Resource Management

Published.

eHoldings

Resource Management

Published.

eUsage

Resource Management

Draft in progress.

Settings

(Multiple)

Handled with the settings’ associated apps

Glossary

N/A

Published.

ReportingReportingPublished.


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

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:

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.




  • No labels