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 Service Mesh Patterns Playground - Layer5
About Layer5 and its projects
The Layer5 community represents the largest collection of service mesh projects and their maintainers in the world. Our inclusive and diverse community stewards projects to provide learning environments, create and implement cloud native industry standards, deployment and operational best practices, benchmarks and abstractions, and more. Our pay-it-forward mentality with every contributor (mentee or not) is a shared commitment by all maintainers (and MeshMates - contributor onboarding buddies) to the open source spirit that pushes Layer5 projects like Meshery forward. New members are always welcome.
Meshery is the open source, service mesh management plane for enabling the adoption, operation, and management of any service mesh and their workloads. There are many service meshes available. Software-defined networking is difficult to understand. Meshery’s aim is to make the power of the network available to the rest of us.
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 service mesh 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 service mesh playground.
Meshery’s genesis is that of helping teach people about service mesh 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 service mesh 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 service mesh. We have a number of community volunteers lined up and committed to collaboration on the creation of this service mesh 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)
|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.|
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.