Marcia Borensztajn will share her plan with us and show us a demo version of a documentation site. She will appreciate any thoughts and comments that we might have.
Doing a tour with various groups.
Three spheres:
- Technical Infrastructure - documentation is currently dispersed. Looking to consolidate around GitHub + static site generator + CMS (to enable contributions from a wider audience)
- Process - documentation becomes part of PO story and definition of done.
- Content - Table of Contents, topics, style, but also what modules are "core" to go-live. Also, contribution guidelines.
Phases:
- Demo site + draft processes. Review candidates for Google Season of Docs (GSoD)
- Work with Marketing and Development (to get Help link in UI). Also work with SysOps for support, pick first app to document, review GSoD projects
- Core "go live" apps, refine process, contribution guidelines, install instructions, GSoD project work
Beyond: dive deeper on apps, dev docs and feedback mechanisms
Open questions:
- One repository per app? Per release? Make docs a separate module in core install?
- Ian suggests bundling per release. Anton points out that maintain multiple releases' documentation may be significant extra work (cherry picking commits). Maintain version numbering for documentation. Looking at URL structure to maintain linkage from deployed modules to correct version of documentation
- If documentation is bundled as a module with the FOLIO install, then that eliminates the issue of looking at the wrong version of the documentation
- What about custom modules outside core? Could documentation be submitted? Big question!
- Mechanism for writing/modifying locally? Workflows are going to be different for different libraries even running the exact same code.
- Customizing FOLIO docs with local institution branding.
Moving forward:
Marcia's slides: FOLIO_Information Plan_v2.pptx