Technical documentation: another way of showcasing your company
Technical documentation is a factor of growth and customer retention that is too often forgotten. Let’s discover together the best practices and some useful tools to have a documentation of the same quality as your customer service.
The days of on-premise software implemented as part of a 6-month project accompanied by the software provider’s experts are over, we are now in the era of SaaS with implementations and onboardings in a week. However, software has become more and more complex with more and more side technical offers.
What SaaS today doesn’t offer its customers to do things their way using an API ?
For whom and why?
A matter for developers
When creating technical documentation, we often make the mistake of believing that it doesn’t need to be very carefully written, because it will only be read by seasoned developers: this is not true!
It must be readable by everyone, even if each person has a different level of understanding of the subject.
In fact, depending on your customers, the technical documentation may be studied by a sales person as part of a call for tenders, by a prospect when comparing the various SaaS products on the market, by a product manager or even by an operational person.
It is therefore your responsibility to ensure that all these types of people can not only find the technical information they are looking for, but above all that they do not leave traumatized…
I can’t count the number of times I’ve been confronted with technical documentation that was so vague that I couldn’t launch a simple API request after reading it.
A growth factor
The second mistake often made is to believe that technical documentation has no commercial impact.
Taking care of your landing page, the description of your functionalities, your competitive pricing, it’s good: making an accessible technical documentation is better!
In the era of full SaaS, a prospect arrives with needs in terms of functionality, price constraints but also requirements in terms of integration. For example, they will want to be able to log in with SSO, access certain information from a third-party application or even synchronize their workflow with yours. And to get all this information, he will turn to your technical documentation…
If it’s not friendly enough, then he might not even contact you, because he’ll be convinced that it will be too complicated to integrate you in his ecosystem.
It’s a shame to lose customers because they think they can’t do something that is actually possible and not necessarily complicated!
Don’t forget that a majority of SaaS customers are very small businesses, often with limited technical staff. It is unlikely that your customer has a purchasing department, let alone a technical consultant for these topics. So, the more simple your documentation presents the possibilities, the more you will reassure your customer by giving him the impression of a smooth and painless integration.
A retention factor
The advantage of a SaaS for the customer is that he can leave whenever he wants: it is therefore necessary to retain him!
Deeper the merrier
A customer who has succeeded in integrating you into his ecosystem is a customer who does not churn: it is therefore in your interest to make this integration as easy as possible.
Some customers will want to integrate as soon as they are onboarded and will therefore often be very accompanied and very accustomed to soliciting the CSM teams, but for many this desire will come a little later when communication is less frequent. This is quite normal, as people will generally allow themselves a few months of use before incurring costs to launch integrations such as setting up an SSO connection or developing a front-end using the API data.
And it’s precisely in this period, when the customer is happy and wants to integrate, that you can lose them if they don’t have a way to make that integration as simple as possible. In every market, there are many competing SaaS and if your customer can’t integrate due to lack of documentation, he will surely start coming back to see what your competitors are doing.
Finally, never underestimate the power that technical teams can have. If your client’s CTO finds the documentation unreadable and doesn’t want to waste time integrating you, you can be sure that this will work against you.
Dos & Don’ts
✅ Dos
- 🖥 A user-friendly UX
User experience is important even for technical documentation: navigation should be simple, different topics clearly differentiated, points of attention highlighted. - ⁉️ Two levels of language
As explained above, the documentation must be readable by both operational people and developers. It must therefore simply address the problems solved while detailing the technical actions to be performed. - 🧪 Integrated tests
The first thing we want to do when presented with a query or a block of code is to test it: so simplify these tests by integrating them into your documentation. - 🔍 Clarity and simplicity
Even if it’s only read by technical people, your documentation should be as simple as possible.
- You need a token to access your API: detail how to get it!
- You use an unusual authentication method: detail it!
- This request uses a parameter like a company ID: explain where to find - 👥 Use personas
Product Management techniques can also be applied to your technical documentation: define the different personas that will read it, their expectations, the language they use…
This way and by putting yourself in their shoes, you will minimize frustration on the customer side.
❌ Don’ts
- 🧑💻 Leave the responsibility to the developers
Of course they are the ones who can create technical documentation, but they are not usually used to adopting a more operational level of language. Documentation management by a PO/PM in close coordination with the developers ensures a good level of language, but also a sufficient level of detail, as the PO/PM brings an outside view on the subject. - 📋 Don’t put an example
This sounds simple and yet there are still documentations that do not provide an example. To show you how important examples are, I’ll take two examples:
- An API parameter can be in the path, the query or the body: without examples it is impossible to know and you have to test all possible solutions…
- An Iframe is one of the simplest things to integrate a SaaS to your website, but if you are not technical, a simple example can save you hou - 🥼 Not providing a test environment
As said above, when we read a documentation we want to test and to test we need: a test environment including a test API, but also an interface. Thus, it is possible to test the request and to validate that the information will be correctly included in the interface that will be used by the operational staff. - 📄 A PDF
No, in 2022, it is no longer acceptable for your technical documentation to be a PDF, for several reasons:
- A documentation must be updateable in near real time. Every time your API changes, you don’t send the PDF to all your customers!
- As said before, a documentation must give examples to test the code and all this is complicated by the use of a PDF, since just copying and pasting from a PDF can sometimes be a hassle.
Personal experience: There is nothing more frustrating than not understanding documentation. I have a very good level of technical understanding especially on API topics and yet I frequently don’t understand some documentation because there are no examples, I don’t know which credentials to log in with, etc. And this is usually the moment when I lose my patience, abandon the topic and only pick it up again once someone has been able to explain it to me (which often postpones the topic for several weeks).
Some technical solutions
Now that we know how to make a good technical documentation, let’s discover some tools that allow to do it easily. I have chosen to present three of them, all available in free versions.
Swagger
Swagger is the Open Source reference for documenting your API and if Swagger Editor, which allows you to generate static documentation, is very well known, their tool Swagger UI a little less.
However, it has only advantages since it allows you to put your API documentation online by displaying the different methods, the data models, to put examples and to test these examples by executing the request directly from the interface.
If you are looking for a simple, efficient and free tool to allow your customers to easily understand how to use your API and to test it: this is the tool you need.
Postman
Postman, is the tool that allows you to manage numerous APIs, to collaborate, to test them and also to document them thanks to the Documentation Tool.
It is already a very interesting tool to have internally to manage your API but also all the APIs you use since it allows you to gather in the same place different APIs, different collections of methods, to manage the environment part but it can be even more interesting for the documentation part.
Indeed, even if the UI of the documentation generated by Postman is very sober, the possibility to generate a Run in Postman button is very practical.
In one click, you can generate the code of a button to add on your website that will allow your customers to be directly redirected to Postman to test your requests. If this button used to redirect to a static version of your query collection, this is no longer the case. The new version allows your clients to fork your collection to test it while still receiving the updates you have made.
Docusaurus
Swagger UI and Postman are very good tools for documenting APIs, but they don’t allow you to document other technical aspects of your product such as SSO connection, your Webhooks or how to integrate it into a website via an Iframe.
Docusaurus is a static site generator in React-js that comes from an open source project from Facebook. Very simple to set up, it will allow you to generate a site with a sober and modern UI to document all the technical aspects of your product.
Easy to set up and deploy (on Github Pages for example), it can be written almost exclusively in Markdown, so it can be used by less technical profiles. Even if it requires more configuration and development than the other two tools, for me, it is the perfect tool to build a real technical showcase of your product.
One of its advantages is also to gather a big community on Github with more than 4000 merged pull requests and some quite interesting plugins have been developed like Redocusaurus which allows to generate automatically the pages for each method of your API from an Open API specification.
Article written by Alexis Colonna.
The opinions expressed are mine alone and I am not speaking on behalf of the company I work for.
What do you think of this article?
If you found this article interesting, click a lot of times on 👏 to let me know and share it around you. Also, feel free to put any feedback or questions in comments.
