2019-03-11 - Data Migration Subgroup Agenda and Notes

Welcome and request for someone to take notes. Notetaker: Tod Olson

David Crossley will join us to discuss Folio documentation,  and what exists out there that may be helpful to us in mapping  and loading our data into Folio.

Main dev site:

https://dev.folio.org/ (use the Search facility)

Documentation issues on the data elements have been around from the beginning, data element documentation is moving slowly, not really fast enough for data migration and reporting current needs.

Describe schema and properties

https://dev.folio.org/guides/describe-schema/

This page came about because of issues encountered in this group, and in the reporting prototype, where Nassib could not get enough information about data points to develop reports.

Documentation comes from two places, JSON schemas and RAML documentation files. Follow the links from the API documentation.

API documentation

https://dev.folio.org/reference/api/#inventory

All of this documentation is generated from JSON schemas and RAML documentation files. Every time there is a change to the master branch of a repository, this documentation views are re-generated. (not the high-level documentation page, but the view pages that it links to.) A report is generated about missing elements (if so, then presented on the pull-request front page). However often filled with stubs, so the report is less effective. Some schemas quite big, not an easy job.

View 2 is the plain view, David's favorite.

There is also a report generated for each module software version. https://dev.folio.org/reference/api/#usage-notes

For each endpoint, the top section is generated from the RAML, with the HTTP method and endpoint and parameters. Lower, the schema is from JSON.

Trouble is that a lot of these fields are missing descriptions. They are slowly being provided by developers and library experts, getting there. May not provide enough information to let you do your job.

JIRA tickets

FOLIO-1568 - Getting issue details... STATUS trying to describe information that is needed, but we are not seeing that always being populated.

Problems/Ideas

Possible that a manual review and sign-off should be added to the Definition of Done?

Version text in the RAML files is often not kept up to date. Most not updated.

Could the module version be listed in the module documentation.

It would be useful to have various cross-reference facilities to link to the relevant documentation for particular versions of a module software. Also by interface and version. Also perhaps for a quarterly release, link to the generated docs for each module.

Bug reports could include questions about what is/is not required and whether marked correctly.