This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Cloud Native Computing Foundation (CNCF)
- Technical writer:
- Shriti
- Project name:
- Improve documentation of SMI & related service meshes
- Project length:
- Standard length (3 months)
Project description
Service Mesh Technology is essentially aimed at providing value to the increasing number of services, by handling all your security, management, and monitoring needs. Service Mesh Interface (SMI) defines a set of APIs for the most common service mesh usage cases (traffic policy, telemetry, and shifting) and enables compatibility between service meshes, which are dedicated infrastructure layers for handling service-to-service communication in a microservices environment. The standardization of these interfaces will provide an enhanced end-user experience and thus, is a future goal for SMI and related service meshes.
Current State:
User Guides: SMI is a relatively new sandbox project, donated to CNCF in April, 2020. As a result, the project is lacking in end-user documentation. Meshery is a service management plane with performance benchmarking for all sorts of services facilitating adoption, configuration, operation, and management of the performance of different service meshes and incorporates the collection and display of metrics from applications running on top of any service mesh. Thus, I would like to start out with a guide for Meshery, which will serve as a starting point for the entire SMI user community.
User Tutorials: Among the existing SMI platforms: The sample application, Learn Layer5, currently serves as a learning device for SMI and as the sample application to perform SMI specification validation against.But otherwise, the SMI projects completely lack end-user tutorials, which is a serious hindrance because of the highly technical nature of the projects. Meshery is the perfect application to showcase the benefits and usage of SMI and the related service meshes, which is why I will be using it as the base tool to exhibit SMI's features.
API Documentation: Non-existent at the moment. SMI and various related projects have their API endpoints defined on a platform; as an example, Meshery has its endpoints defined at server.go (https://github.com/layer5io/meshery/blob/master/router/server.go), but they are neither well commented or documented externally. This can be resolved with meaningful documentation of the API's and can be enhanced by adding ways for the users to test its endpoints and preview its features.
Analysis:
User Tutorials are created to allow the user to engage and have a test-run of the Software. They need to be interactive and aesthetically appealing to hold the user’s attention and most importantly, easy to use.
However, for writing or hosting User Guides, a more mature format would be advisable as User guides often serve as a reference guide or a place to get a quick fix for issues. Rather than being interactive, they need to be well structured and focus on improving clarity, coherency, and good user flow.
A possible solution to this would be to make separate User tutorials using Google Codelabs and an independent User Guide with the help of Jekyll and finally integrating them along with the API documentation to give a well-rounded experience to both the end-user and future collaborators.
Target Audience: SMI projects provide deployment and operational practices, learning environments and performance benchmarks to all the projects under them. It caters to both individuals and organizations.
User Guides: I will be targeting beginner users, with no presumptions of pre-existing IT knowledge on the user end. Target: Beginner Users Reason: Used mainly as a vast Reference guide, which will need to be updated with time. This will include in-depth explanations and helpful tips, to make sure that the user has all the information they need to set up and work with a service mesh. The Guide will be made more engaging and user friendly by adding videos, pictures, screenshots and GIF's, wherever needed.
User Tutorials: Target: Beginner Users Reason: The focus will be to make the tutorials engaging and aesthetically appealing to hold the user’s attention and allow a smooth test-run of the software, which will lead to a better understanding of the Service Mesh Interface.
API Endpoint documentation: Target: Advanced Users Reason: This section focuses on using the more complex features of the service mesh, which is more in the interest of advanced users with a basic level of IT knowledge. Advanced users will be looking for concise tutorials which can also be used as reference guides, if needed. The Endpoint documentation should be written in such a manner, so as to make it easy to update without compromising on its accuracy or consistency. This should preferably be an automated process.
Resources: User Tutorials: Google Developers Codelab - Used to make interactive and comprehensive end-user tutorials. Benefits: - Can produce sandbox tutorials. - Has a hands-on approach. - Written using Google Docs and supports Markdown text. - Can be monitored using Google Analytics - Easy to observe user traffic. - Easy to use. Produces aesthetically pleasing tutorials which allows the user to engage directly with the software without any direct investment.
Google Codelabs can be enhanced and easily deployed using the CLaaT (Codelabs as a Thing) project - This is a program that offers a command-line tool used to convert tutorials written in Google Doc using Markdown into the codelabs (HTML) format.
User Guides: Jekyll - The existing documentation for meshery.io, which can be found here is hosted on Jekyll and uses the Docsy Jekyll theme. It uses Markdown, liquid, HTML, and CSS to produce ready to host, static websites and runs on a Ruby development environment. Benefits: - Can host sites directly from GitHub repositories. - This a well supported Project with a very active community - User Guides and enhancements can simply be added into the existing SMI and Meshery documentation, without having to bother about migrating onto another platform.
API Documentation: Swagger (alternatively, Swaggo) will be used for creating the API documentation for SMI and Meshery. It is an elegant solution for writing API documents. Benefits: - Documentation From Your API Design: Ensures your documentation stays up-to-date as your API evolves. - Documentation From Your API Design: Can be auto-generated from API definitions. - Maintain Multiple Documentation Versions - Customized API Designs
Project Goals: - Use Google Developer Codelabs to create interactive end-user tutorials for SMI and related service meshes using Meshery as a tool. - Create an end-user guide, using Jekyll for service meshes. - Use Swagger to generate API endpoint documentation for SMI. - Make the project community driven so that future and current users or developers can easily continue adding to it under the guidance and moderation of the SMI community.
Timeline: The proposed timeline can be found here: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
Structure: The proposed structure for the User Guide can be found here: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
Why this Project? The service mesh community is expanding at a lightning fast pace, enabled by its recent integration as a sandbox project into CNCF. However, the project is witnessing a serious dearth of documentation, both for end-users and developers. I have played around with various service meshes in the past, including linkerD with EmojiVoto app, Istio with its bookinfo application and Hashicorp’s Consul. I have also tried SMI traffic split and have implemented various validation rules on my service mesh configuration. The learning process is fascinating but highly technical and can be a put off for new users as well as developers, looking to take their first steps into the service mesh community or utilizing service meshes for their own personal or professional projects. I would like to bridge this gap, which can only be done with efficient and well documented guides and tutorials.