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)
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.
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.
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/
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.
Another attribute of good documentation is context. I have documentation on Docker, Node, Yarn, etc. When I put things together, which directory should I be running from? What user/role is needed for execution? We follow the rules dictated by the tools, but what rules do we need to state about what we create with the tools?
I’m reminded of trips in cars without cup holders, GPS and automatic windows. You would get where you were going but there was a lot more effort for events that were part of the trip that weren’t actually driving the car, because they weren’t integrated.
What is it about the documentation that helps you as a tool user?
Examples for all available options are the most important for me. Some tools are so amazing and offer a ton of different options to integrate and use but they are lacking examples of all usages. Also important is to keep it up to date. Integrate a checkmark in the PR that when changes are implemented the documentation needs to be updated as well as this is often forgotten.
What do look for in good documentation? Where should you find it? Can you contribute to it, and if so, how?
I mostly look for how to use the tool or how to change the integration to make it work for me. Most helpful for that are examples in the readme or as code in the repository. When I use an option that isn’t documented very well I open an issue, fork the repo, add my example, and get a PR ready. It takes me 10 minutes but it saves other people the long googling to find the right way of using this option.
What sort of documentation do you find unhelpful?
Outdated, lack of examples, and very hard to navigate through.
Good documentation is essential to learning about a new tool. If it is not documented well, it is very hard to ramp up with it’s use.
Good documentation contains examples of not only how to use something, but why you might use it a certain way. It is easy to read and grok what is going on.
I would hope that it would be found on the official site for the tool, but various blogs may have good content on a specific tool as well.
Many tools now are open source and are happy to allow folks to contribute to their documentation.
I’d say the opposite of what I consider good. It contains little to no examples of how to use the tool. I suppose no documentation at all is the least helpful.
Have you seen the amazing schedule and registered for Test.bash();?