2020-10-13 Meeting notes

FOLIO Documentation

Marcia Borensztajn

Three spheres:

• Technical infrastructure

• Process

• Content

Phase 1 - finishing up now

• Stand up demo environment

• Test using Git as repository

• Draft high-level structure

• Draft initial topics for one app

• Explore potential style guides

• Explore options to externalize writing

• Review candidates for Google Season of Docs

  • Have 2 writers now, one for installation and one for Resource Access

Phase 2 - moving into soon

• Work with marketing & others

  • Determine look and feel

• Create entry point via folio.org

• Work with development

• Add a Help icon to the UI

• Establish a docs repository on the FOLIO GitHub site

• Enable the association of a specific release of FOLIO with a specific set of docs (version control)

• Work with SysOps

  • Move demo site to production environment

  • Est presence in JIRA for issues/bugs

• Select  first app to document

  • Use to understand potential model for end-to-end process

  • Establish documentation development roles for the the app

• Select Google Season of Docs projects

Phase 3

• Determine core set of apps needed to "go live'

  • Develop contents as resources allow

  • Refine content creation and maintenance processes

• Develop contribution guidelines

  • End user documentation

  • Developer documentation

• Installation instructions

• Some of the this content can be sued to serve both sys admin and developers

• Works on Google Season of Docs projects

  • Depends on the writer/project selection

Beyond Phase 3

• Additional app content development

• Deeper dive into Sys Admin documentation

• Deeper dive into Developer documentation

• Feedback mechanisms

Marcia gave an overview of the demo site and gave examples of decisions still to be made about organization

Patty - settings example- can they be cross-linked so there are multiple access points?  MB-yes

Patty - right now we may not be sure what a field is, for ex, can the documentation explain what they mean or used for MB-yes, eventually

Tod - how do we document at a level that is maintainable?  Too granular a level might not be sustainable. MB - that's why she doesn't like to use a lot of screen shots, but need some.    Need "last changed/modified/reviewed" status on the pages so people can judge the currency

Tod - libraries might want to have their own versions to accommodate local workflows.  MB - the issue has come up, people should be able to download the documentation and be free to do with it what they want.  Then they have to handle their own updates and help links.

Tod - what's the prospect for using some completed documentation to inspire others to help write some. MB - have to manage multiple writers carefully 

Patty - what about templates? MB - she's looking into template options.  POs and SIGs can contribute a lot, give feedback, give guidance on what people struggle with most

Kelly - have you thought of a documentation SIG?  MB - yes, she has asked the SIGs she's visited for volunteers, something may come of that

MB - what seems most critical right now? Kelly - data import, orders & finance (what the fields are and what they do); Patty - organizations (impacts decisions down the line); Kelly - start with the ones that are more complicated and less intuitive

Jacquie -It might be good to have a map that indicates which functions/features/apps are related to all others.

Kelly - if institutions have started their own documentation it would be good for Marcia to have

There is now a Slack channel for documentation

Topics for next week

From Sept 29: 

The issues identified here need to be brought to attention of PC - what are priorities? NFRs for the base and put off features, or quick & dirty features to fix later?