Ask HN: How do you write customer documentation for your application?

[tpetrina]

As applications become more complex they start requiring proper FAQ, documentation and more. How would you approach it from the tech/writing side? How to keep screenshots up to date? What about ease of editing/publishing/translating? How should articles be linked from the app itself? I have a feeling that web never got that built in ? Button Win32 apps used to have.

[Jugurtha]

We still are not good at it. We're developing our internal machine learning platform as a normal product[0] and treat questions as failure demand[1] to update documentation, or eliminate the friction that lead to the question.

The whole point of the platform is to take a lot of the burden of machine learning off of the user, so that complexity is handled by the platform to make things as simple as they possibly can be, without becoming rigid.

If many people ask us about something, there's an opportunity not only to document that, but to reduce ambiguity upstream so the question never gets asked again.

We also monitor errors and usage and ask our users and colleagues questions on their usage, or why they were not able to do something, and learn from that.

We also are our users and when we use the platform and find we're having trouble remembering things, we add that in. For example, when we added the functionality to deploy a model, we added a tutorial on how to invoke the model with different languages, how to make a request, etc.

Not the best at UI/UX because it's not our background, but we're improving.

- [0]: https://iko.ai

- [1]: https://vanguard-method.net/failure-demand/

[ronronron09]

Decent user documentation can help your end customers succeed with your product but arranging it can be challenging. Do lots of research and learn how to make it easier. You may need to use https://isaccurate.com/translation-services-boston to translate it to broader audience. User documentation guides your customers, helping them to use your product properly while also assisting them with any difficulties that arise

[afarrell]

The best forms of documentation are, in order:

1. Encapsulating complexity to eliminate the need.

2. Well-designed UI Affordances to eliminate the need.

3. Documentation presented just in time at the Point of Action

4. A concisely illustrated mental model explanation and some specific searchable how-tos.

5. Well-written answers on StackOverflow.

For more on this, see the Django community and Write the Docs.