Launching a dev-friendly documentation website!
OpenPaaS SDK Barcamp
Open Source software live thanks to the contributions of passionate developers. At Linagora, we develop such software and our wish is that any interested devops and developer can easily use our product and also bring contributions. The open collaborative platform OpenPaaS is one of these software!
OpenPaaS team frequently organizes barcamps (team building sessions on targeted topics) and improving OpenPaaS documentation website was one of the two topics on the agenda of the SDK barcamp which took place in Paris from 3rd to 5th May with teammates from France and Tunisia.
As a member of this barcamp I will present you my team’s reflection:
our starting point, what we launched during the barcamp and on how it has evolved today.
Before the SDK Barcamp - our existing API documentation
Until now we were using Swagger to expose the REST APIs of OpenPaaS because it’s a very practical and reliable framework.
But looking objectively at our existing APIs documentation, we concluded:
- one good point: we are happy that OpenPaaS does have an API documentation :)
- two improvement axis:
- OpenPaaS deserves a documentation that is not restricted to API. We need to explain how to add a new module on OpenPaaS, how to integrate external services or applications with OpenPaaS…
- This user interface is definitely too cold.
In fact, if we look around us we notice that current collaborative services API documentations are well groomed and trendy which makes them welcoming and attractive to devops and developers (e.g.: Slack, see below). Moreover, these documentations address more than API part: integration…
During the SDK Barcamp - what we bootstrapped
The objective was to provide all the documentation needed by a developer or a devops on a single attractive place.
We first chose a nice template…
…integrated our existing Swagger file in it and then enriched the site with the following sections:
- APIs: how to use OpenPaaS APIs and what they are
- OpenPaaS Integrations: how to integrate your services with OpenPaaS
- OpenPaaS Modules: how the OpenPaaS modules are built
- OpenPaaS Module deep dive: how to create your own OpenPaaS modules
- Keep in touch subsection providing Twitter, Facebook and GitHub… links!
After the SDK Barcamp - what we do daily
At Linagora we have the will to have an alive OpenPaaS documentation site so we took the decision of spending 1.5 day of every sprint of every team to work on documentation. As soon as the functionality of our OpenPaaS platform evolves, our teams of developers update the documentation website for each OpenPaaS feature.
As a conclusion
The documentation website of a software project is an important showcase of what a company does and how it does it. Its completeness and its attractiveness will undoubtedly convince developers & devops and so lead to to constructive partnerships. At Linagora, we’re convinced that documentation is key, and we wanted to spread the word!
From my point of view this barcamp was first a good opportunity to gather some of my teammates working in other locations and thus maintain the team cohesion. I knew most of the participants and also met for the first time 2 Tunisian OpenPaaS developers!
Secondly, it was a defined time to share our views about the OpenPaaS documentation website and that was constructive. I’m pretty satisfied of the completeness and sobriety of the result and more satisfied about the current continuous enrichment of the documentation website.
If we had to redo this barcamp I will suggest a previous brainstorming including the whole OpenPaaS team: maybe others ideas could have come out.
About the current result of our documentation website I think that we could customize lightly the chosen template with Neoma, the UX and design agency within Linagora.
Interested in discovering the second objective of the SDK barcamp? Read If OpenPaaS then Todoist article.
Keep in touch with us on Github, Twitter and apply to our jobs offers.
