Google Season of Docs gives technical writers an opportunity to work with open source projects. Layer5 is applying to participate in the Season of Docs.
Program Administrators and Mentors
- Lee Calcote (@leecalcote)
- Abishek Kumar (@kumarabd)
2021 Project Details
Project: API Docs for Meshery’s Cloud NativePatterns Playground
Layer5
At Layer5, we champion developer-defined infrastructure, giving engineers the power to reshape application delivery. We empower operators in reimagining how they manage modern infrastructure: collaboratively.
About Meshery
As a self-service engineering platform, Meshery enables collaborative design and operation of cloud and cloud native infrastructure.
About our Community
Layer5 is all about its community of contributors. We have designed an onboarding program customized to meet newcomers where they’re at and developed an onboarding buddy program, MeshMates with individuals dedicated to assisting contributors. Layer5 and Meshery have been around for a year and half and have a healthy, growing community of 300+ contributors. The layer5.io website itself is open source and created by 140+ of our contributors.
Impact of Google Season of Docs Participation
Layer5 and its mentors have participated as mentors in GSoD 2020, GSoC 2019, 2020, and are in 2021. Mentoring and seeing others learn and grow is what Layer5 is all about - it’s a platform for mentees to hoist themselves up on and leapfrog from. We’re a platform for shared success.
Participation in GSoD will be most meaningful to the community. The cloud native playground will be the first of its kind. Similar in nature to https://labs.play-with-docker.com, but with a full, interactive set of API documentation to accompany the learner.
Technical writers and other contributors are what comprise Layer5 - an open organization, built for the community by the community. Many student contributors have been placed into new jobs with technology companies like Red Hat, Microsoft, and VMware to name a few of the larger organizations. Layer5 expects much from interns and in return, we put them on stage at DockerCon and KubeCon. We promote them and uplift their works. There are many, many examples of this on the layer5.io websites. A number of former interns are now project maintainers.
GSoD 2021 Project
About the project
Goal: Create the world’s Kubernetes playground.
Meshery’s genesis is that of helping teach people about cloud native technology and enabling to operate this type of cloud native infrastructure confidently. The proposed project is aimed at furthering this mission with interactive API documentation connected to a Kubernetes learning playground (a running instance of Meshery). This project sits squarely in the crosshairs of our purpose - both for Meshery and Layer5.
The project’s scope
We will create a new set of interactive documentation for Meshery users to both learn how to use Meshery, but also confidently adopt and operate any cloud native tech. We have a number of community volunteers lined up and committed to collaboration on the creation of this CNCF playground. The technical writer will collaborate with other engineers, working with Swagger and Docusaurus.
Work that is out-of-scope for this project:
- Creation of the Open API specification for Meshery
- Deployment of Docusarous
- Visual design of the site
We will bring support from the Meshery CI WG, provide a full-time visual and user experience designer and well as three dedicated core maintainers of Meshery. We have one strong technical writing candidate for this project, and estimate that this work will take six months to complete. We will support this technical writer and prioritize any dependencies on the project or community that they may have.
Measuring project success
To measure success, we will track:
- The number of new API playground users (quantitative - tracked by the system)
- The number of repeat visits of the same users (quantitative - tracked by the system)
- The number of failed attempts to invoke an API (signifies poor documentation) (quantitative - tracked by the system)
- Feedback from users on how intuitive the documentation is (qualitative - tracked through user polls)
We would consider the project successful if, after publication of the new API documentation:
- The total count of performance tests run by Meshery increases by 10% (see the current count on https://meshery.io)
- The new number of new Meshery users increases by 20% (currently at ~1,000 users)
Project budget
| Budget Item | Amount | Running Total | Notes | |
|---|---|---|---|---|
| Technical Writer stipend | $7,000 | $7,000 | Technical writer is expected to learn much and be diligent with their efforts. They should be well rewarded. | |
| Mentor volunteer stipend | $500 | $7,500 | This volunteer mentor will be put much time into the project and into the success of the technical writer; should be rewarded. | |
| Microphone for Technical Writer for remote collaboration | $150 | $7,650 | Clear communication is key to successful, remote collaboration. This is meant to facilitate collaboration, be a reward for participating, and be useful long-term for the technical writer. | |
| Total: | $7,650 |
Additional information
Previous experience with technical writers or documentation
Our mentors have managed teams of technical writers working on documenting enterprise-grade software at large technology companies (Cisco, Seagate, SolarWinds). During the span of time, he has worked with technical writers in DITA and post-DITA environments (from Word to FrameMaker, structured writing, online help, various CMSes, git). Our mentors have worked with technical writers on documentation strategy, creating document sets, covering the full spectrum of reader personas.
Previous participation in Season of Docs, Google Summer of Code or others:
Layer5 and its mentors have participated as mentors in MLH, FOSSASIA, GSoD 2020, GSoC 2019, 2020, and are in 2021. Mentoring and seeing others learn and grow is what Layer5 is all about - it’s a platform for mentees to hoist themselves up on and leapfrog from. We’re a platform for shared success.
We interact daily over Slack, and have an open source project meeting everyday, which are posted to the community YouTube channel.
