A short guide on Open Source documentation - introducing the new Golem Docs + sharing our findings for the community

Lowering the barriers of entry for users and developers is something the decentralized ecosystem recognizes as a big pain point. Comprehensive, complete and ordered documentation is one of the elements to address towards the aforementioned goal.

Our UX team has been working in close collaboration with our developers on researching the best documentation standards in technology and finding a standardized solution for our own repository and knowledge bases. Golem has existed for a bit more than three years nowadays. Our repository has amassed a whopping +180.000 lines of code. We are working on APIs, have a user base, and are integrating new use-cases, so for us, standardizing and improving our documentation was a  high priority.

Thanks to our constant communication with the community, we found out that a large portion of our user base is actively using our documentation. Our user base is very active on the support chat, and we were convinced that most of the community members were just using this tool to gather information regarding Golem’s issues and installation processes. To have a single source of truth for All Things Golem was something high up our wishlist, as for some time we had high-level documentation on our website and more tech-savvy information on our GitHub. We wanted to merge those two worlds into one without sacrificing any of them.

Through our research to achieve this goal, we found out there was no need to reinvent the wheel. We started wondering: which web 2.0 projects have the best documentation standards, what can we learn from them, and how can we adapt it to our project? So we took it from there.

We asked several developers in the space which were to the best of their knowledge, great documentation examples, and most people agreed that Stripe, Twilio and Docker were some of the favorites. Through our research, we identified the best components of each and implemented those in our own documentation.

Additionally, we didn’t want to write the code for it from scratch, as this would bring unnecessary distractions for the team, and Golem needs to be in continuous development. And we found our silver bullet. What is better for an open source project than implementing the best open source solutions out there? Enter Docsify. It’s clean, lightweight, easy to build and change, it has a ton of useful plugins, and is so simple that even designers can use it without much of a hustle.

We are pleased to introduce our new documentation. We believe that this new layout and content structure, plus all the information we included alongside visual guidelines (electron infographics), will be able to make Golem more accessible to our users.

Keep in mind that our docs are a living organism that is constantly being worked on. We know that there are parts of the documentation that will require additional love. We wanted to share current version to our community as fast as possible so they would have better tools at hand, and get your feedback.

So, there you go. A short explanation on our approach, our findings, and how to take the best out of existing examples and adapt them to Web 3. Check our findings in this slideshow - we hope this is helpful!

Got ideas on how to improve our documentation? Please send us feedback in our Chat - channel #UXfeedback!