[GSOD] Operation Clarity - Refactoring SkyWalking Documentation

[Superskyyy]

Operation Clarity: SkyWalking Docs Fixit - Apache Software Foundation (Apache SkyWalking)

About Apache SkyWalking

Apache Skywalking is a top-level project under the Apache Software Foundation that graduated from the Apache incubator in 2019. SkyWalking is a powerful and widely adopted Application Performance Management (APM) platform that allows developers to monitor, diagnose, and optimize the performance of their heterogeneous distributed applications. SkyWalking is designed to work with microservices architectures and dominant cloud-native environments in today's industry and actively seeking to integrate with state-of-the-art technologies, including service mesh, eBPF and AIOps. Skywalking provides end-to-end tracing, metrics, logging analysis, and service topology visualization, allowing developers to identify performance issues and optimize their application's resources. Besides the core platform project, SkyWalking owns over 30 ecosystem projects maintained by different teams and volunteers to support diverse programming languages and frameworks.

The SkyWalking project has a diverse community of contributors and users worldwide, including individual developers, startups, and large enterprises. To our knowledge, large-scale deployments of Apache SkyWalking widely exist in the industry. As of 2023, the Apache SkyWalking ecosystem has received contributions from over 750 individuals of diverse affiliations and is rapidly growing to cover more industry and even research (anomaly detection) use cases in observability. Skywalking is licensed under the Apache License 2.0, making it free to use and modify for anyone.

Funding the Apache Skywalking project would positively impact its broad open-source community and the world by empowering developers to create high-performing and reliable applications. As SkyWalking has introduced more features in recent years, there is a need for experts in technical writing to facilitate the growth of our documentation so that it can be available to more developers worldwide. As more and more applications move towards distributed systems and microservices architecture, the need for APM tools like Skywalking will only increase, and funding the project would enable it to continue to improve and meet the evolving needs of developers.

About Our Project

Project problem

As the Apache SkyWalking community grows, we noticed a few vital concerns around our documentation that a non-profit open-source project could not efficiently resolve. SkyWalking is used by organizations and individuals in many different countries spanning each continent, and we receive reports of inaccuracy in the documentation that blocks users/developers from understanding certain critical features. Such confusion often leads to the unnecessary opening of duplicated discussions at various user channels and burdens our users and maintainers. The SkyWalking documentation has been evolving for a long time since the early days, yet with more features being implemented and changed; we find our current documentation contains many issues, including incorrect grammar and outdated statements that either should be updated or removed. Such problems negatively impact the documentation's usability and significantly block the progress of documentation translation (since we need first to fix the English version). As we plan to expand translation and optimize documentation search, we want to see an effective fixup of the current documentation that best expresses SkyWalking's usage and setup.

Having a strong and reliable base English version of the documentation allows future volunteers to work on translating the latest documentation to other languages without constantly correcting the base version. We would like the technical writer to put themselves in the user's shoes, providing a comprehensive overview of our documentation and noting the friction of understanding necessary setup steps/notes of features. The above challenges, when addressed, will benefit not only current users of Apache SkyWalking but also ease the process of new contributors, leading them to a more effortless onboarding experience.

Project scope

The Refactoring project (Codename "Operation Clarity") will:

• Audit the existing Apache SkyWalking Main project English documentation and create a friction log of the current documentation. The technical writer should place themselves in the shoe of the user and note the parts that are unclear/imprecise for the critical sections around installing SkyWalking, customization/integration and debugging.
• Use the friction log as a guide for bridging the gaps in the documentation, create patched documentation based on the original documentation and lint the grammar/tone of the documentation.
• Help create a short and practical guideline for SkyWalking contributors so that they realize previous errors in producing documentation and facilitate good habits.
• Incorporate feedback from core maintainers and real-world industry users (there will be volunteers) and the Apache SkyWalking community.

Work that is out-of-scope for this project:

• This project will not require the technical writer to consider other ecosystem projects in Apache SkyWalking (which has over 30 projects, including agents). The technical writer should focus on the OAP platform at the core of the SkyWalking ecosystem.
• This project will not require the technical writer to create a translation of other languages in any form. This project will not need the technical writer to understand every technical detail of Apache SkyWalking.

We are currently seeking strong candidates for this project, and we estimate that this work will take five months to complete (1-2 months for onboarding/reviewing and learning about SkyWalking, and 3-4 months for refactoring and incorporating feedback). Apache SkyWalking Project Management Committee (PMC) members will assist in this process and promptly answer the technical writers' questions.

Measuring project's success

We incorporate several key measures for evaluating the project's success. On the qualitative measure side, we have multiple volunteers from the core SkyWalking team willing to provide feedback on the refactoring process and ensure the project's progress. Furthermore, SkyWalking has various user channels, including Slack, GitHub Discussions, Maillist and Tencent QQ, to gather feedback on the refactored documentation and evaluate if it provides significant value to the SkyWalking community.

Regarding quantitative metrics, we adopt the open-source CHAOSS (Community Health Analytics in Open Source Software) model to evaluate its impact, an empirically proven effective way to model software ecosystem health. We will track several metrics, including the diversity of new contributors/recurring contributors to the ecosystem and the frequency of issues/discussions that ask for clarification over documentation, etc. We will verify if the documentation refactoring will result in a more friendly welcome to new users/contributors who wants to familiarize themselves with the domain. We will evaluate metrics each month after the refactoring.

Furthermore, we plan to evaluate the user feedback through a survey. Since SkyWalking has IRC channels with more than 4000 users, we plan to conduct a survey that collects user feedback to compare what was before and after the refactoring process. The goal is to evaluate the documentation's appropriate usage of technical jargon and readability.

We would consider the project successful if, after refactoring and publication of the new documentation:

• The number of new/recurring contributors quarterly increase by 10-20%.
• The number of issues/discussions on unclear documentation decreased by 30%.
• The user feedback from surveys indicates increased satisfaction compared to the original documentation.
• The volunteering translation (beyond GSOD) can proceed smoothly without constantly correcting the original documentation (because of seeing errors).

Timeline

Dates	Action Items
April	Hiring technical writer and conducting orientation and introduction.
May-June	Audit existing documentation and discuss with mentors and the community to gather concrete refactoring ideas for specific sections.
June- Sep	Working on refactoring documentation.
October	Project completion and write a short guide for future contributors.

Project budget

We request project funding of US$10,000 to support hiring an experienced technical writer.

Budget Item	Amount	Running Total	Notes/justifications
Technical writer hiring for audit, testing, and refactoring work	8,000	8,000
Project volunteering stipends	500*4	10,000	Volunteering, including providing feedback, assisting and sourcing for the technical writer and coordinating the project progress & final evaluation (conducting the survey and analyzing metrics etc.).
Total		10,000

Additional information

• Previous experience with technical writers or documentation: 【没填完的地方If you or any of your mentors have worked with technical writers before, or have developed documentation, mention this in your application. Describe the documentation that you produced and the ways in which you worked with the technical writer. For example, describe any review processes that you used, or how the technical writer's skills were useful to your project. Explain how this previous experience may help you to work with a technical writer in Google Season of Docs.

Core contributors active in the SkyWalking community have experience working with technical writers dominantly in revising translations. Specifically, two PMC members have experience reviewing the translation outcomes of the technical writer. On the other hand, all volunteering mentors have extensive knowledge of producing practical technical reports in the observability domain and have evaluated documentation from various contributors at Apache SkyWalking. Lastly, one volunteer is in software engineering research and is familiar with documentation prioritization techniques and state-of-the-art research in applying automation and optimization tools for documentation.

• Previous participation in Google Season of Docs, Google Summer of Code or others: Multiple mentors and core contributors of Apache SkyWalking have/are mentors of GSOC since 2018. We also have experience with Open-Source Promotion Plan (OSPP) and several other hackathon events (e.g. Hacktoberfest). At SkyWalking, each mentor connects with their students actively and assists their participation throughout the event. To our knowledge, we have helped at least four students succeed in the GSOC event (maybe two more before SkyWalking's graduation from the Apache incubator) and over 15 students in similar events, among whom some became Apache committers. This year (2023), we are also preparing to mentor 6 GSOC projects as Apache SkyWalking is growing rapidly, and mentors are ready to guide new contributors. In such a sense, we would love to see the refactored documentation in place so the student contributors can easily understand the project ecosystem as observability is a rather complex domain.

[Superskyyy]

This is the place for hosting the project proposal and further information regarding the project. We welcome potential technical writers to reach out to me at my email address (GitHub profile).

[Superskyyy]

This project is set for Google Season of Docs, not Google Summer of Code. Please do not get confused :)