| 52 | Reviewing technical documentation with the Folio Technical Writer & Editor, Marcia Borensztajn | all | - Technical documentation that system administrators/operators need
- What is already there ?
- Here is an overview of existing documentation that is relevant for SysOps: Existing Documentation (SysOps SIG)
- What should the documentation look like ?
- Audience, purpose and context of the documentation that we need
- What needs and expectations do Folio system administrators have towards a technical documentation ?
- What should be in the documentation ?
- Marcia Borensztajn, FOLIO technical writer / documentation specialist, just recently joined the project. Experience with a wide array of industries in Israel and the US
- The common thread is the understanding of the community of knowledge users: who needs to consume what information for what purpose? How leverage knowledge assets
- In FOLIO, meeting with POs, SIGs, SMEs, developers etc.
- Understanding what content currently exists. Developing an understanding of how FOLIO works (ops, data, apps, interactions between them)
- Working on managing a common, effective writing style, selecting tools
- Long-term goals: create a repo / KB to enable successful interaction with the community (current and future members).
- Create a standardized approach for content toward a consistent experience
- Provide localization of content
- Standardize the process for contributing, reviewing, and publishing project documentation
- FOLIO applied to the Google Season of Docs - Google matches technical writers with open source projects. FOLIO has been accepted into the program!! This will help us onboard and mentor writers. We will accept 2 writers; applications are coming in.
- Marcia’s email: marcia1.folio@gmail.com
- Also on Slack in the FOLIO workspace
- Q: What documentation is already there, and what do we need as sysadmins?
- sysadmins are focused on getting the system running, keeping it healthy and secure, and how to properly update the system.
- sysadmins really need a common, robust architectural diagram
- A sysadmin new to the project can get the system running, but they don’t really know how it works.
- Q: Distinction between what sysadmins need vs what developers need? Does it start with the same content, and then diverge?
- One thing to consider is that just getting the system up isn’t enough, there’s a lot of data to populate (and probably migrate)
- Michelle will forward to Marcia some examples of the steep learning curve of certain aspects of the system
- Marcia will focus on developing the right infrastructure for the documentation, and how to incorporate documentation into the code release processes (as part of the definition of “done” etc)
- Rancher may need to be a focus as it moves into more general use
- One overall challenge has been the the uneven quality of our extant documentation
- Would different SIGs require different styles of documentation?
- User-facing documentation is another matter, maybe more aggregated
- Marcia’s team will also work on end-user documentation
- Discussion of different audiences’ needs. Another flavor is the “power user” type who starts as an end user and then wants to delve deeper
|