While working in a product-based start-up, the chances are that you would require to make a simple, yet powerful documentation for easy product integration. So how can you build simple product documentation within no time - let's discuss with a valid scenario (I know I like to explain things with scenarios 😁).
Consider you are developing a product which requires a set of integration steps to integrate your product, for example, a library, SDK, etc. The product success purely depends on the fact that how well you project your product integration documentation to the audiences. For the sake of simplicity, we will consider that our product is a mobile SDK (android and iOS) which has to be integrated by mobile app developer. Also, assume that you have separate teams to maintain your SDK of android and iOS.
Let's first understand some decision parameters that would help us identify the correct implementation for our product documentation (integration guide):
Simple
Documentation should be very simple to understand and easy to navigate. As a developer community, we know how cumbersome it is sometimes to understand the integration documentation. No matter how good you explain the steps, if your documentation is not simple and easy to navigate, it will confuse the reader more. Therefore, keep it as simple as possible for the users (generally developers) to understand the steps for integrating the SDK in their mobile app.
Markdown Enabled
I am not gonna discuss why Markdown in detail here. Besides, I am a big fan of markdown because of its simplicity. It is very easy to write and format the text as we want (no wonder why I write blogs on dev.to 😆). Moreover, because of its popularity, most of the developers understand this markup language. Hence, very easy for our mobile SDK developers to maintain the documentation by themselves.
Open Source
I feel, everything that we developers do, reaches an optimum level with collaboration. By making this documentation open-source, I want to make it available for the users, i.e. developers to post any probable modifications as per their understanding to improve the overall integration experience.
Deployment and Hosting
As it is clear from the above point, I will be using GitHub for maintaining the documentation project. Not only that but I also want it to be deployed and hosted with the Git Workflow. Which is when I learned about static site hosting services like GitHub Pages, GitLab Pages, Netlify. This made my life easier as whenever we push any changes on master branch, it would update the overall documentation on the go. Also, you can host your documentation on a custom domain 😌
Maintenance
The most important aspect of any project, the maintenance should be well thought off! Since we are building a product integration documentation, it tends to be updated very frequently. I want the process to be so simple that our SDK team should be able to push the changes live without any team's support.
And so I started my research to hunt for a feasible way of achieving this target. I came across some really good documentation experts like read-the-docs but as we discussed earlier, I want something which helps me create the documentation, like a documentation generator (which will be cost-free as well 😛). Then came a term - static site generator. It basically generates a complete static HTML-based site. It does not rely on databases or other external data sources and therewith avoids any server-side processing when accessing the website. I knew that I am looking something similar but with a markdown capability. Quickly enhancing my search, found this awesome site - Docsify.
Finally, I started creating the documentation with one of the Docsify's pre-loaded themes and within no time, I was able to complete the documentation. The Docsify's documentation provides you a way to deploy your documentation to GitHub Pages, GitLab Pages or personal hosting as well with no issues. Also, there are some handy plugins like copy to clipboard, pagination, and a lot more.
Final Thought
Surely, there are many other documentation generators available like Docsie, which you can look out for as per your requirements. It also helps you manage your product documentation versions. Here, I just wanted to explain how easy it is to write, publish and host your product documentation!
Some things are simpler in reality but looks difficult to achieve
See ya! until my next post 😋
Top comments (0)