Building the Documentation - Motivation, Choices and Lessons Learnt

Creating the Documentation website for Documenso, Inc. was on our minds for a long time.

We finally released it last month, and the community's response was overwhelmingly positive.

In this thread, I'll discuss the motivation behind it, our choices, and what we've learned.

1. Motivation

The simple answer is to make our users' lives easier.

No matter how simple or intuitive you try to make an app, there are always things you can do to improve the users' experience and reduce friction. Instead of trying to figure things out on their own, they can consult the documentation to avoid frustrations and save time.

Moreover, Documenso is open-source, and people outside the team contribute to the codebase. That means they need to set up the project on their machines and learn the different parts of the codebase.

The documentation contains all that information. It also provides clear guidelines and best practices for contributing, making it easier for them to get up to speed quickly and contribute effectively.

Lastly, we used to receive the same questions over and over again. With the release of the documentation, the number of repetitive questions has dropped considerably.

In summary, the motivation was to:

- help users make the most of Documenso

- enable contributors to get up to speed quickly with the project

- reduce repetitive questions and confusion

2. Choosing the tool for building the documentation

There are quite a few tools for building a documentation website. Some of the available options are:

- Nextra

- Mintlify

- Docusaurs

- Starlight (Astro)

- GitBook

... and many others, probably.

Our shortlist included Nextra, Mintlify and Starlight.

Ultimately, we decided to go with Nextra. It's open-source and built on top of Next.js, which we already use for the Documenso app. It also has (almost) all the features we need.

But using Nextra wasn't without its challenges.

Setting to set it up in the monorepo was a bit painful because it just didn't want to work. Also, the documentation changes weren't always visible because of the cache. So, we had to disable the build cache in the Vercel dashboard.

Lastly, it would be awesome if they supported an interactive API reference. See this example from Docusaurs to understand what I mean.

But other than that, we're really happy with Nextra.

3. Documentation organisation

We split the documentation into 2 parts:

1. Learn - This part is concerned with the app itself. It's about how to use Documenso and make the most of it.

2. Build - This part is for developers, and it's concerned with contributing to the project.

We separated the two because they cover different things. This way, people can quickly find what they need. No confusion. No wasted time.

4. Learnings

1. Make the documentation dumb simple. This is not a writing contest, and you're not writing a novel, either. People are busier than ever. Help them find whatever they need as quickly as possible.

P.S.: That doesn't mean you can get away with bad writing and grammar.

2. Add screenshots when relevant and possible. As the saying goes, "A picture is worth a thousand words."

I don't think this needs more explaining. Screenshots are incredibly useful for providing a visual complement to your written instructions.

3. If you add code snippets, add them as text. This way, the users can easily try the code by copying the snippet.

Don't add them as images. Nobody has time to type the code from your images. If you really want to add screenshots, add a link to a gist with the code from the image.

4. Make the documentation skimmable. It might be the third time I say this, but people are extremely busy. Help them find what they need as soon as possible.

To do that:

- avoid big blocks of text

- split large blocks of text into smaller sections

- emphasize (bold, callout, etc.) important info

- use images/screenshots/diagrams

- add code snippets

- use lists

By the way, I'm creating a course about technical writing if you want to learn more about this topic. Join the waitlist here technicalwriting.online.

5. Avoid adding unnecessary stuff. Focus on the most important things and the parts that are likely to create problems and confusion.

For example, don't write an in-depth section about updating the user's profile settings. Instead, focus on more important features/parts.

6. The documentation is not a one-off thing. You don't build it and then forget about it.

The documentation is ongoing work. Make sure it is updated periodically as the application evolves. Otherwise, it will soon be irrelevant and a waste of time.

For a technical writing consultation, book a meeting here: catal.ink/writing-consultation.

To learn about technical writing and how it can boost your career, visit: technicalwriting.online.

The End

That's all. Thanks for reading! I hope you learned something new.

Check the documentation website ?? docs.documenso.com/

Star the repository ?? documen.so/github

Start using Documenso ?? documen.so/new