What does good tool documentation look like? Share an example of helpful tool documentation and provide reasons why it’s helpful. – 30 Days of Tools, Day 15

Congratulations, you’ve made it halfway! This is Day 15 of the 30 Days of Tools challenge. To document or not? That is not a helpful question!


What does good tool documentation look like? Share an example of helpful tool documentation and provide reasons why it’s helpful.

  • What is it about the documentation that helps you as a tool user?
  • What do look for in good documentation? Where should you find it? Can you contribute to it, and if so, how?
  • What sort of documentation do you find unhelpful?

Feel free to reply to this post and share wherever you like, on the MoT Slack, LinkedIn, Twitter using #30DaysOfTools, Racket, your blog, with your team and any place you feel might inspire yourself and others to do the same. Let’s learn from each other throughout October. Visit the 30 Days of Tools page and select the “Subscribe to Topic” button to receive each daily challenge direct to your inbox.


:point_right: Have you seen the amazing schedule and registered for Test.bash();?

It’s on October 28th, 10am-10pm UK time. Available with a Pro Subscription or you can purchase a ticket.

3 Likes

For example in Postman documentation on the API which can be imported from a swagger, is so valuable.
Our devs write examples or extra info in the docs which is auto-generated onto the swagger, which we import to Postman, which also imports the documentation.
It really helps the less technical people to understand how to use the API.

  • Good documentation is short and straight to the point.
    Where should we find it? In 1 spot, all documentation of all tools/frameworks/… should be gathered in 1 spot so people don’t have to go and search all over the place to find the right documentation.

Everyone can contribute to it, there is a tips & tricks section in which you can add a way of working with the tool.

  • No documentation
  • Outdated documentation
  • Documentation without examples
  • No visuals added (purely text without screenshots)
4 Likes

When I was picking it up I found Serenity’s documentation to be quite decent

The actual documentation is fine, nothing out of the ordinary, but it stood out to me because from the get-go I could take a look at mini-demo projects, like this. Immediately clear what it does, how it does, what to expect if you migrate you almost don’t have to even do a POC - just checkout and browse. It also gives good hints about best practices and patterns that the creator wants you to use.

Examples, the more the merrier. And a short getting started guide. If I need more details I can go looking but I should be able to get started quickly.

Worse than no documentation is documentation that is out of date. Countless times did I start implementing something only to find out that that API has been deprecated many releases ago and the actual way of doing things is totally different and undocumented, very frustrating.

3 Likes

In a documentation I want examples, picture, up to date one (like others said).
Random ideas:

  • I also like troubleshoot part.
  • I prefer a ‘writing doc’ (I do not know how to say that in English) than video documentation. I cannot do ctrl+f into a video. And online documentation.
  • I also think version and date of the documentation is important (Is it an old doc? A new one?).
  • I loved 30 days of postman for developers I learnt a lot about howto use Postman with it (I was more a challenge than a documentation).
  • I don’t like Cypress documentation! You need to do so many searches.

Sorry my message was messed up…

4 Likes

I agree with what other people have said. Some other stuff - I think that it’s important that the tool is designed to be easy to learn, easy to use and easy to document. Otherwise the documentation is trying to fight some of the tool’s usability battles, which is rarely as effective as a tool that’s easy to use in the first place.

This is stuff like:

  • There are defaults that handle the common and/or simple cases, with the option to easily branch out to other cases. The alternative is stuff like having to give lots of detail and spend lots of effort for every case.
  • The tool should have a small number of concepts that are necessary, and keep them as close to the underlying problem domain as possible.
  • The tool should be self-consistent, which is related to but slightly different from the previous point.
  • It should be obvious what the tool has done and why.
  • The tool should be predictable. This is a consequence of the previous things. Instead of having to learn every detail and use case by rote, I should be able to learn some stuff (from documentation and from using it) and then use that knowledge to predict how things will be for a new use case. I should then get clear feedback that confirms my prediction (or not, with explanation) when I use it.

A case in point is the language R. It grew in an organic way, and so wasn’t consistent within itself. Then Hadley Wickham and friends carved out a new version of the most commonly-used subset, called the Tidyverse. It’s got a small set of concepts, is self-consistent and so easier to learn. It’s also easier to document well - this is some of the best technical documentation I’ve read. https://r4ds.had.co.nz/

3 Likes

It’s well structured, searchable and contains relevant examples, and it’s also kept up-to date.

Like the InteliJ docs, for example:

I mostly look for examples on how to do things, start looking for it on official sites. As far as the contributions go, lot of opensource projects keep their docs in markdown format on GitHub (or similar places) and people are encouraged to make contributions.
Rest-assured (Apache license) docs for example:

If it’s too long and hard to navigate, outdated, lacking practical examples and/or has incorrect info.