Why Documentation is Important

Documentation (or “docs”) is such a key part of any open-source software project. If you have good docs, users will find it easy to get started. They’ll also be able to find answers on their own for the majority of questions as they use the software. 

Even before I start evaluating technical products or organizations, I usually check out their docs. If they have good docs and other on-boarding resources, this provides confidence in the quality of their product. It also speaks volumes about the organization’s culture from attention to detail and community support to overall transparency.  

In the past, the main users of open source software were developers. Today, however, open source software is used by many end users who aren’t developers such as business analysts, data scientists, and others. This is why having good docs is more important than ever. 

History of TiDB community contributions

From the beginning, TiDB welcomed community contributors (more than 800 today and growing) to our projects—the same is true of our docs. Our docs pages are also a popular destination as they were visited by more than 300,000 users over the past 12 months. 

We dedicate a lot of time and resources to our docs. But we also realize that no docs are perfect, and there’s no one better than our user community to help us make them better.  

End users can provide important insight as consumers of both our software and docs. In addition, as anyone who’s done any type of writing can relate, it’s always a good idea to have someone proofread your work. 

Announcing TiDB Docs Dash 2024

In this spirit, we’re excited to announce the inaugural TiDB Docs Dash on January 9 -11, 2024. The goal of this event is to bring TiDB community members together to have a fun and collaborative event where everyone can help improve TiDB and TiDB Cloud docs (they both reside in the same repository). 

Below are some examples of how community members can contribute: 

• “Debugging” docs: Follow the steps in the docs (e.g., of a new feature) to make sure that the instructions are complete and accurate. 
• Suggest edits to improve readability of a docs page. 
• Find/fix typos or grammatical errors. 
• Translate a docs page (e.g., from Chinese to English)

This is just a partial list. We’re sure TiDB community members will also be able to suggest other areas where we can make improvements. 

How will TiDB Docs Dash work? 

Before the event, we will create a list of GitHub issues that community members can work on. Each issue will be associated with a docs page that needs to be debugged, translated, or improved. 

During the event, community members can work on these issues by either submitting a PR or further contributing to issues with comments or suggestions in GitHub. Community members will earn points for each PR or issue they contribute to during the event (with more points awarded to PRs vs. issues).

We’ll also welcome contributions outside of these issues, especially for things like fixing typos or improving readability. Community members will again earn points for PRs or creating new issues. 

At the end of the event, we will tabulate the scores for all participants. We’ll have fun awards and TiDB swag for the Top 5 contributors, as well as for anyone who made a valid contribution. We have more details on the scoring system, event swag, and other important information on an event page dedicated to TiDB Docs Dash. 

What’s Next? 

If you’re interested in helping improve TiDB docs, and want to join a fun community event, please save the dates of January 9-11, 2024 in your calendar!

We also created a new #2024-tidb-docs-dash channel both on our Discord and Slack. We encourage you to join those channels to look out for announcements! Just post any questions or suggestions for the event. 

Most importantly, we encourage everyone to think about their experience with TiDB docs and where you wish it could be better. You can share your thoughts on our Discord or Slack channels. 

We look forward to collaborating with all of you during our first TiDB Docs Dash!