Organization or Project: Casbin
Organization Description:
Casbin community is committed to providing users with open source single sign-on, rights management global solutions. In this year's GSOD activity, Casbin community mainly participated in two projects: the permission management system Casbin and the single sign-on system Casdoor.
What is Casbin?
Casbin is an authorization library that supports access control models like ACL, RBAC, ABAC for Golang, Java, C/C++, Node.js, Javascript, PHP, Laravel, Python, .NET (C#), Delphi, Rust, Ruby, Swift (Objective-C), Lua (OpenResty), Dart (Flutter) and Elixir. Docs site: https://casbin.org/
What is Casdoor?
Casdoor is a UI-first centralized authentication / Single-Sign-On (SSO) platform supporting OAuth 2.0, OIDC and SAML, integrated with Casbin RBAC and ABAC permission management. Docs site: https://casdoor.org/
Authors: @ bnuluohf @ Yash Pandey @ yoyo314 @ Selflocking @ jakiuncle @ cofecatt @ wenxuan70
Problem Statement/Proposal Abstract
Tutorials are lessons that take the reader by the hand through a series of steps to complete running Casbin & Casdoor code. They are what our project needs in order to show a beginner that they can achieve something with it. They are wholly learning-oriented, and specifically, they are oriented towards learning 'how' rather than learning 'what'. Tutorials need to be useful for the beginner, easy to follow, meaningful, extremely robust, and kept up-to-date.By improving the documentation of Casbin & Casdoor, We hope to encourage more people to use and contribute to our community！
Project Description
Creating the proposal
The Community Organizing Committee of Casbin heard about the Season of Docs program through the official website from Google's Open Source Programs Office. The project authors of the community consulted with several core members, and agreed to create a proposal. The core contributor to the Community Documentation project（@bnuluohf）volunteered to work on the draft proposal for review. Several core members of the community discussed the program, and agreed to create a proposal. After discussing and incorporating feedback from community members, our community submitted a proposal. At the same time, the community assistant @Tina agreed to help creating the Open Collective account required to participate in the program and oversee payments.
Budget
We found some technical writers who had participated in the GSoD documentation season and invited them to consult with us about their budget planning. Finally, our project author and three long-term maintainers of the technical documentation negotiated and settled on this budget for the project. Since there are many Chinese readers as well as English readers of the technical documents, in addition to the project funding, the Casbin community raised about $1,000 of its own money to recruit volunteers to assist the technical authors in translating the written documents.
Participants
The core team working on this project was:
• @ bnuluohf （IrisL, technical writer, Long-time maintainer of community technical documentation）
• @ Yash Pandey (technical writer)
• @ yoyo314, (Document translator and embellisher)
• @ Selflocking (technical writer)
• @ jakiuncle（technical writer）
• @ cofecatt（technical writer）
• @ wenxuan70（Document translator and embellisher）
We found YP（Yash Pandey）through the Season of Docs GitHub repository list. We thought his experience (YP has participated in the GSoD activity in previous years as a technical author) matched well with our project. YP communicated with the community by emails and talked through the project with us, making several very valuable suggestions that we incorporated into the proposal. During this time, we also posted technical writer recruitment information through various channels and contacted our long-time maintainers of technical documentation to ask if they would like to join the campaign (this is how IrisL was contacted). The community's documentation project consists of two sub-projects: Casbin's technical documentation and Casdoor's technical documentation. YP is mainly responsible for Casbin's technical documents, while IrisL is mainly responsible for Casdoor's technical documents. We also recruited two volunteers to help translate and polish the documents（@ yoyo314 @ wenxuan70）. Unfortunately, midway through the program YP dropped out of the project due to lack of personal time and energy. In order to ensure the smooth progress of the project, we recruited three more technical authors to continue to write technical documents（@ Selflocking @ jakiuncle @ cofecatt）. All members communicated with each other through issues on github or emails. Due to the different time zones of members, there was poor communication at the beginning. Later, with the increase of cooperation time, we constantly overcame difficulties and gradually got on the right track. We were fortunate enough to work with seven document technical authors and complete the documentation of the project. We believe that this experience will also benefit them, and now several of them are continuing to contribute to the Casbin community, which is the best thing!
Timeline
While we waited for the Season of Docs program to announce participating organizations. Our community preliminarily drew up the outline of the technical document and made an overall plan for the technical document to fully prepare for the new members to join.
Once we got the good news that we were selected for Season of Docs, We immediately worked with the proposed authors to set a schedule for the project.
Results
The technical documentation need to be useful for the beginner, easy to follow, meaningful, extremely robust, and kept up-to-date. In this project, the improvement criteria for the technical documentation are as follows： Allow the user to learn by doing Get the user started Make sure that the tutorial works all the time Ensure the user sees results immediately Make the tutorial repeatable Focus on concrete steps, not abstract concepts Provide the minimum necessary explanation Focus only on the steps the user needs to take Based on this standard, we finally formed two complete technical specifications for the rights management system Casbin（https://github.com/casbin/casbin-website-v2） and the single sign-on system Casdoor（https://github.com/casdoor/casdoor-website）, which were published on the Casbin community website.
Metrics
In our proposal, We focused on three data points：the tutorials page views, the visit duration on tutorials, and the bounce rate of tutorials.
We would consider the project successful if, after the publication of the new documentation:
The tutorials page views increase by 50% The visit duration on tutorials increases by 50% (>3 minutes) The bounce rate of tutorials decreases by 25% (<50%)
We track all three metrics (page views, duration of visit, and bounce rate) on a monthly basis after new technical documentation is released. We also tracked the number of user entry questions, starting each quarter after the document was published. Before the technical documentation project started, Casbin had 3,000 visits per day and Casdoor had 300 minutes of visits per day, with a bounce rate of 75%. After the new document was released, daily visits to Casbin and Casdoor almost doubled, and bounce rates dropped by about 30%. We believe that the new technical documentation will enable our users to become more proficient in using our system, and indeed a significant number of users have already responded positively to the new documentation.
Analysis
We are very pleased with the results of our Season of Docs program and we judge it a success. The new technical documentation created by the technical writers is clear and helpful to developers, and we have seen significant increases and decreases in the three metrics we focus on. Our users have also given us a lot of positive feedback on the new technical documentation, which is very encouraging for us, and we will continue to improve and keep this project going.
However, there are still some regrets, such as the lack of some specific use case screenshots in the new technical documentation, which we believe will be the reason for continuous improvement in the future. In the future, we also welcome more people to join the community documentation work, together to improve the technical documentation!
Summary
Overall, our community had a perfect Season of Docs experience, and we achieved the goals of the original program and even better results. A big part of the success of this project was that we were lucky enough to meet our technical writers. Among our technical writers, some have a lot of technical writing experience, some have no technical writing experience at all, some are long-time technical maintainers of the community, and some have never been involved in a community project. In any case, everyone gets together in the same project, asks questions together, solves problems together, learns and helps each other, and finally forms a beautiful technical document, which is the best result! We would advise other projects to: (1) A clear plan should be made for the document project. The prototype of the document should be drawn up first, and a document sketch should be drawn up in mind. Only in this way can the team members have a clear idea of what the community wants. (2) We should be good at accepting the reasonable suggestions put forward by members, fully think and transform each suggestion, and finally make it become an important suggestion in the construction of the document. (3) We should be good at finding the bright points of each contributor and let them give play to their strengths in the team, so as to fully mobilize their enthusiasm and make them more responsible and belonging.
Appendix
The official website of Casbin：https://casbin.org The official website of Casdoor：https://casdoor.org The github link of Casbin：https://github.com/casbin
Acknowledgments
Our team would like to acknowledge the following people and things:
• @ bnuluohf would like to thank all the family and friends who supported her in the program
• @ Yash Pandey would like to thank all the technicians who worked with him
• @ yoyo314 would like to thank all the good fortune she had
• @ Selflocking would like to thank the community gave him the opportunity to participate in activities to realize his dream
• @ jakiuncle would like to thank for having a remote job and an income while he is home quarantined for COVID-19
• @ cofecatt would like to thank all partners in the struggle
• @ wenxuan70 is grateful to be able to have a remote job during the holidays to support his studies and life