| title | author | image | tags | redirect_to | |||||
|---|---|---|---|---|---|---|---|---|---|
Rebirth of sensenet docs |
|
../img/posts/docs-sensenet-com.jpg |
|
As we started working on SNaaS it became clear pretty soon, that the developer documentation needs radical changes both structurally and in appearance.
The product is intended mainly for developers, so the time has come to serve this main target group not only with the software but also with sufficient and quality content.
Our old documentation was made when sensenet was a completely different software. As an ECMS it had multiple layers not only for different types of developers but also for end-users and system operators. Since now sensenet is a headless solution most of the documentation target groups are gone, so the old structure was no longer sustainable. wiki.sensenet.com was built with MediaWiki that was ok for the old software but as we were moved to GitHub with sensenet we wanted to make the docs open source and community driven as well, which made the old solution difficult to maintain.
We've decided to create a new community site generated by Jekyll which serves the documentation, the blog and other community related needs. It seemed to be a good idea till we reached the number of docs where it became unusable and unmaintainable. So, we came to a turning point where we had to rethink everything that we thought about developer docs and ask the community for help.
Hacktoberfest 2019 was a good opportunity to reach fellow developers who were already somehow connected with sensenet. We've created a survey with various question about what they are expecting from a developer documentation. We were curious about the ideal length, structure and type of docs, we were surveyed the user habits, needs and wants. The results made clear how we should structure and prioritize the work on the new docs: the most important is to create a ton of tutorials, make the concepts clear both for developers and non-dev decision makers and add a well-structured and complete API reference.
Well, I'm happy to announce that the new documentation site is up and running. Not all the docs are ready yet but we're quite happy with the work we've done with the concept and API docs and of course we're never stop improving and expand the docs based on the audience's needs: we're constantly working on end-user docs for the admin-ui and trying to create as much tutorials as it is needed to present that using sensenet is super easy and effective.
Okay, the site is ready, and the new docs will coming constantly. But how can we keep the momentum? Our product team is now quite small and improving a product is usually more important than working on the docs. So, we decided to choose a dedicate day when we are all working only on the docs. Aaaaand Kontent Kedd ('kedd' is tuesday in hungarian) was born! Every other week on tuesday the whole team is working to make the documentation better and better. 💚
As I mentioned above keeping the docs on the community site was problematic in several ways. We had to choose a future-proof solution that makes possible to come up with an open, community driven, well-structured and easy-to-use documentation page. The code base of sensenet is on GitHub since ages so as the community site and we did not want to change that for the new docs either. To generate the actual site our choice fell on Gatsby which not only indicated that we became familiar with a technology that was completely new for us, but it also generated some possible future tasks like creating a Gatsby source plugin for sensenet or improving our OData requests for collection of binaries.
While you are discovering a new technology and its documentation effective searching is the key and so was as for as while we were developing the new site. In addition to quick search the docs are grouped and ordered in a way that helps you learn new things step-by-step. The docs are organized in multiple levels which makes the connections easier to understand and all the docs have a 'pager' with which you can navigate back to the previous or forth to the next topic.
The top-level menus are completely designed by the above-mentioned surveys results. Concepts containing sensenet basics not only for developers. Tutorials and Example Apps help you start with sensenet offering you source code as step by step guides and downloadable GitHub projects. Admin-ui Guides is a place for useful manuals for the admin surface. In the Integrations menu you would reach the demonstration of current integrations and some help on how to integrate sensenet with anything. Last, but not least at the API Docs you can find collection of references, code snippets and examples in sort everything you need to complete a project.
Just like the software, its documentation is open and stored on GitHub. Any suggestion, question and contribution is welcome, if you have any feedback for us, we will be happy to hear it on GitHub or via chat.