How to write technical documentation? (help)
We are planning to launch our SaaS base product soon. How technical documentation or knowledge base articles should be written? Must they be written by developers? Please share your experience.
Also, I would appreciate if you share good free or cheap services to create a knowledge base site.
I'm CTO of our SaaS and write most of the help docs myself.
Could do with a little more coverage in the docs, but often gets left in the "do it later" pile, I typically add a new doc when I get tired of answering the same question too many times.
Our docs are hosted on intercom articles, which made sense as its our primary support and communication platform.
@tkarimli You can use for the public end-user documentation Knowledgebase from Confluence like this https://support.atlassian.com/
Confluence has default templates for any types of documentation for a project.
https://www.atlassian.com/software/confluence/templates
OR simple use Intercom.
We at Countly write our documentation mainly with product owners, or developers. If it is too technical, a dev writes it, and then it goes to grammar / syntax check, and then published. You may want to check it here, it is pretty extensive and 250 pages long already: https://resources.count.ly
While we use readme.io, there are several options / alternatives / open source software for document management out there. Check Product Hunt - most of them are listed.
Good luck!
Thanks all too amazing answers. ;)
Hi @tkarimli, if it helps I put together a website full of resources on how to write technical documentation: doctoolhub.com. I'm a tech writer myself so if you have any questions feel free to ask away!
Hi @tkarimli
Is the documentation internal or public?
For internal documentation, worked on several products where Confluence was used for knowledge base articles. I'm currently using it as a requirements repository for my dev team.
As for authorship, that really depends. Can your techs write coherent documentation? Are they willing to?
Other common authors would include your Requirements/Business Analyst or Product Owner to write the docs.
I'd say public docs need to be reviewed by someone whose role is writing-intensive (and i'm not talking code).
Hello @fcdk1927,
Thanks for your response. I'm the co-founder and senior developer of the mentioned SaaS product by @tkarimli. Documentation will be public for the end users. We think them as kind of "how to" articles.
For me personally writing documentation or knowledge base article is not easy actually. I agree with you about the public docs. They need to be written or reviewed by someone whose role is writing-intensive.
For public-facing doc, a good tech writer is worth their weight in gold. They will need participation from devs, architects, business analysts, product managers (whichever of those you have), but the actual stringing-together of words, decent structuring, etc, will be taken care of.
Tech writers tend to be contractors, so it's easy to find someone you like, and bring them in when you've got a new release or whatever.
Internally, I've used Confluence as well. Unlike most Wikis, it can produce reasonably-formatted PDF output too, which can be useful.
If you're a Zendesk customer, their integrated knowledge-base thing is ok too.
I'd recommend pairing Help Scout docs with iorad for the fastest creation of docs within a knowledgebase. Includes wording + screenshots + translation option automatically.
Ideally, you need to describe every step/piece of code/function in your documentation. But if you are out of resource (time/people) start from the most significant one. Try to figure out which piece of documentation is critical for those who don't know your product. Then step-by-step add everything else.
Don't forget to add FAQ, search, index to your documentation. Make sure that it doesn't look like a chapter of "War and piece" and you interlace text with pieces of code, illustrations, warnings etc.
It doesn't matter who exactly is writing, but they just should know the core needed for end users and speak in their language.
When I write docs I always refer to existing ones. I love documentation created by Webpack, it's a really good example.
G'luck.
Hi Taleh!
My cofounder and myself wrote our docs. He writes all of the most technical parts, then I come back through to test and add to them. It's not perfect but it has worked so far! https://dev.cott.io/docs/ I'm happy to chat more about my experience if you are interested. ben@cott.io
what tool are you using to host/manage these docs?
We host our doc site out of GCP. The downside is that every time we make changes, we are required to build and deploy the new site.
Looks good to me! What I didn't get how to get to your main site. The logo links to the docs itself but not to the website.
Thanks for catching that error. I will get that fixed. Our main site is www.chainoftrust.io We host them out of different places.
No problem and thanks :)
There is now a button to take you back to the home page. Thanks again for the catch!
Hehe, but how a user will be able to return from any other doc's page? I would suggest putting a link or a button to the left menu what is visible from any page.
Another question is why did you separate these 2 domains so drastically? You would just create a subdomain like docs.chainoftrust.com or so. Now it's pretty confusing :-0
@Zencentric thanks for the feedback! We are using https://jekyllrb.com/ for our docs and self hosting them. Our main website is on wix. We attempted to combine them but ran into DNS problems with wix. It is something we will get to, but every min working on that is a min that our devs aren't working on the product.