Technical Documentation for startups - an opinionated guide

Your software is as good as its documentation. Even if it's a truism, it's worth remembering, especially when creating a SaaS solution with self-service capabilities and versatile APIs, or when building open-source (no, README.md in your GitHub is not sufficient).

Big tech companies know it very well. They invest significant money in creating and maintaining their documentation. They use dedicated tooling and have teams to build it. But what about startups? They are usually focused on building the product and acquiring customers. In this post, I give you my opinionated guide on how to create world-class documentation without investing.

Believe me, you can't afford to have bad documentation!

It is my ambition to say in ten sentences what others say in a whole book.

Friedrich Nietzsche

Artistic presentation of Docusaurus - generated with Stable Diffusion (Stable Diffusion Web)

Required features

Before we jump into the details, let's define what qualities should an ideal solution have.

• Easy to set up - it must be operational in no more than one day
• Free or cheap - it should be free or cheap to use (at least at the beginning)
• Easy to host - it must not require any special infrastructure or maintenance
  • Netlify or Vercel are preferred as deployment platforms
  • custom domain support is a must
• Easy to start writing - it should be easy to use for the author
• Easy to extend and modify - it should be easy to extend and modify
  • it should be possible to add custom pages
  • it should be possible to use custom components
• Advanced features available - it must be possible to enable and use advanced features as they will be needed
  • $\LaTeX$ support
  • UML diagrams
  • code snippets
  • translations
• SEO friendly - with no extra effort
  • it should be possible to add custom meta tags
  • it should be possible to add custom headers
  • it must be performant (Lighthouse score > 90)
• Versioning - it must be possible to version the documentation
• Search - it must be possible to search the documentation
• Analytics - it must be possible to track the usage of the documentation
  • Google Analytics is preferred
  • cookie consent is a must
• API documentation - it must be possible to document APIs
  • OpenAPI support is preferred
• Community - it must have a community
  • it must be possible to ask questions
  • it must be possible to get help
  • it must be possible to contribute
• Auditable - it must be possible to audit the documentation
  • it must be possible to track changes
  • it must be possible to review changes

This is a long list, isn't it? Is it exhaustive? Probably not. But it's a good starting point and for the majority of startups, it should be enough, at least that's what my experience tells me.

The solution

In my career, I worked with teams that used many different tools to create technical documentation, ranging from proprietary software like Dita to homegrown solutions. All of them had their pros and cons, but none of them was perfect. With the birth of Jamstack architecture, the situation changed. Many great tools emerged, and some of them address many (or even all!) requirements from my list.

Gatsby, Next.js, VuePress, MkDocs, Docsify, GitBook, Jekyll - all of them are great choices, yet my favorite is Docusaurus.

info

Check the comparison of Docusaurus to all of the mentioned tools here.

Why Docusaurus?

Docusaurus is a modern static site generator (SSG) that allows you to create documentation websites. It is built on top of React and uses Markdown as the primary source of content. It is open-source and maintained by Facebook.

Let's take a look at the mentioned qualities and see how Docusaurus addresses them:

• Easy to set up - it is possible to set up a basic documentation website in - literally! - 5 minutes see the official tutorial and check yourself

• Free or cheap - Docusaurus is free and open-source - check their GitHub repository

• Easy to host - Netlify and Vercel are supported out of the box, but it is possible to host it anywhere you want; obviously with custom domain support

• Easy to start writing - out of the box, Docusaurus provides a great writing experience; it is possible to use Markdown, MDX, and even custom React components

• Easy to extend and modify - the framework is built with React; adding custom pages and components is a breeze

  • whenever a standard component is insufficient or requires adoption you can customize it using the so-called Swizzling
    • as an example check the comments at the bottom of this page - it is a custom component that I added to the default Docusaurus template

• Advanced features available - with a ton of plugins, it is possible to add almost any feature you can imagine

  • $\LaTeX$ support via remark and rehype plugins:
  $$e^{i \pi} + 1 = 0$$
  • UML diagrams via Mermaid plugin:
  • code snippets are supported out of the box:

  console.log('Docusaurus is so cool!');
  • translations are supported out of the box via the built-in i18n framework

• SEO friendly - Docusaurus supports all you need in terms of SEO - see the official documentation

  • Lighthouse report (when deployed via Netlify) usually yields a score of close to 100/100/100/100
  • it supports image optimization out of the box which is crucial for fast loading times (see the image at the top of this page)

• Versioning - yes, you guessed it right - it is supported out of the box

• Search - supported via plugins - from free options (pre-index on build) to paid options, like Algolia

• Analytics - fully supported via plugins

• API documentation - with Redocusaurus - an OSS implementation of Redocly - you get all you need to document your APIs

• Community - to say nothing - it is outstanding! Check the Discord channel and see for yourself!

• Auditable - your documentation is stored as code - all you need is there as if it was your application code

Moreover:

• out of the box, you get a great-looking website that is fully responsive and accessible
• a powerful blog engine is included
  • with multi-blog support, you can also use it as a news section or Release Notes pages

The only thing I struggled with was the cookie consent banner that I had to add manually. I achieved the basic consent feature using react-cookie-consent and swizzling the root application. Not a big deal, but it would be nice to have it out of the box.

How to write the content?

If you ask a professional Technical Writer about all the do's and don't's of writing technical documentation, you will get a long list of rules and guidelines. I'm not a professional Technical Writer, but I've written a lot of technical documentation in my career. I've also read a lot of technical documentation. Based on my experience, I can give you a few tips that will help you write good enough documentation:

• all best practices are nicely explained by Google in their Technical Writing Styleguide
• express your thoughts clearly and concisely, and ask LLM (like GPT) to help you formulate your ideas according to the style guide (I guess you can come up with proper prompts)
• use tools like Grammarly to check your grammar and style - even the free version is great!
• don't be shy - with the help of the tools mentioned above, even as a non-native English speaker, you can write great documentation

tip

Done is better than perfect! Make it useful and usable, and don't worry about the rest. If you think your community can help you polish the docs, Docusaurus allows navigate to GitHub directly from the page and submit a PR.

Summary

This blog, as well as the documentation for co.brick observe, - the startup I'm currently developing - are both built with Docusaurus. I'm very happy with the results and I can recommend it to anyone who needs to create a technical documentation website.

If you want to learn more about Docusaurus, check the official documentation. If you need inspiration on styling and customizing your website, check the Docusaurus Showcase pages. Lots of great examples there!

No excuses now - go and build your documentation website! If you have any comments or questions - let me know in the comments below.