Technical documentation I love

[faultables]

Writing documentation––especially the technical ones––is little bit challenging. We are trying to engage our audience (mostly developers) by telling what our platform do in abstract way. It's not how to use the "app", but the "platform". So we will face less visual content but specs.

I'm trying to figuring out some local platform in Indonesia, like Midtrans for payment processor; Kata.ai for Bot platform, Qiscus for Chat SDK, etc.

Based on my discovery, they were trying their best to provide great documentation. This is so excited although developer relationship ecosystem in Indonesia is still relative small remembering our developer-first product is rare. So, this is a points how to create a technical documentation your audience will loves. Yes, I am one of your audience.

Reading Experience

Giving great reading experience is not always about beautiful user interface. This is how I really enjoy reading Git Rebase manual for example.

It's quite, distraction-less, and clear.

I don't need floating-button on the right that asking me for the feedback. If it good, it's good. If it bad; hard to understand, etc, I know where to complain it.

This is how Kata.ai gives a great reading experience, with beautiful user interface, and great UX (almost-zero latency while navigating to another page on desktop-based device with 10mbps internet connection. Yes, thanks to Gatsby)

i18n

Understanding where our audience lives (and what language our audience speaks) is important. Especially for the "local" product that targeting "global" audience. Mostly we are too focus to providing "international" language like English until we are forgot to provide with our native language we speak.

Midtrans did this, although the default language was English (hopefully because they don't track their user geographic so they don't use it to automatically redirect us based on native language we speak).

Why does we should care with local language? Did you realized why does most successful open source project accepting "translate" task pull request?

Versioning

Whether as developer or user, versioning is really important. User doesn't care are your API using GraphQL or REST, they only care "This should be work, because I was read it here".

Imagine when your user got frustrated integrating with your API, because they use different version with your platform? Or, they use not-noticed deprecated API that you don't support anymore?

This is how now from Zeit still respect their old version by not deprecate it

And yes, they giving us the "why" with old version and "why" and "how" with new version.

In documentation-level, this is how Qiscus give us an option to see documentation version of their platform

Although the option is still the "latest", possibly soon they will release major changes version of their platform.

Tutorial

Because trial-and-error is the best way for learn! It's like, you now, I have no idea with what NL Studio from Kata.ai was. Based on their documentation, they tell me:

In Bot studio tutorial, we learned how to make keyword-based chatbot to order pizza. However, keyword-based chatbot is not so smart. In this tutorial we will learn how to enhance the chatbot using NL Studio.

Okay cool, I can make bot that speaks sundanese language I guess.

This tutorial is so long, and clear.

Changelog/Release notes

I took example from Kata.ai (again). They have "Release Notes" section, although it placed on Overview accordion (First, I should click Overview so I know Release Notes was there. Second, I have no idea why Release Notes placed there).

But sad to see I don't see versioned-docs from Kata.ai (although they have major version changes on their API). Maybe all of their users was using the latest version, I guess?

Changelog is great. Some user loves new features, bug fixes, performance optimization, and more. Because this is a documentation, any patch version should not affected with docs.

The missing part: Live Example

This section tells the some parts I love but I don't see it from local platform I know.

You know, tutorial is so long. It's like, if I want to try start using payment processor, I need to:

• Setup my stack based on their SDK
• Install the dependencies
• Writing some minimal frontend
• Reading the README files about what this example is doing

Yes, I can just clone the example repository code or download the zipped files if they still use it. But, how about if you have 5 core features? Cloning all that 5 repositories? Placing it in one place and separating it by using monorepo concept?

What if we simplify it like this:

So I don't have to setup (and coding) just to figuring out how it works and how it looks like.

And yes, with actual data in "sandbox" environment.

That's looks better.

---

Writing documentation (both for internal or external) is pretty hard. That's why in every documentation page they always ask for feedback. All of what I wrote here was about documentation in high-level view (and partner API), not low-level view API documentation itself (which is usually for internal usage).

We are ready to help if you have some problem related with documentation writing, technical writing, and engaging developer community.