There's very few documentation experts out there. Those who write the docs are either devs who write broken English, or English majors who don't understand a lot of the tech stack. In either case, they usually miss the target persona, and what are the reader's needs.
Writing docs is hard :/.
1. An understanding of what variables are available, and where. Hugo nicely collects a lot of useful info but it is difficult to know what it all is and where it is. https://gohugo.io/variables/page/ is a good start but it is difficult to know how these are populated.
2. Hugo is implemented in Go, so under the hood everything is strongly typed. But the Hugo documentation throws that all away and presents the dynamically-typed interface that Go's html templates provides. The problem is, figuring out what anything can do is made very difficult by that. So, ok, I have a .Content or a .Data for this page... but what is that? Is it a string? Is it an object? If so, what can I do with it? I have to experiment to find out, or grep over a couple of templates to figure it out.
Honestly if I had to make just one suggestion to the Hugo docs team, it would be, strongly type your entire documentation suite. Tell me what the type of everything is, and the resulting methods/functions I can use it with. (If it's an interface, fine, I don't mean all the maximally static types necessarily.) That wouldn't fix everything, but it would fix the frustration I experience of visiting https://gohugo.io/variables/page/ and still wondering what any of that stuff actually is.
Docs are hard and thankless, but ¯\_(ツ)_/¯ them's the breaks.
Other things that I pay attention to are built-in integrations with other tools, the ability to import and export data, familiarity to users, similarity to existing tools, tutorials that leave users confident, and documentation with examples of use cases are all similar factors.
How shit the product is for Wordpress is a matter of debate, but the documentation and ecosystem around it is robust enough to make it fairly easy to hack and use/abuse to do what you want it to.
This right here is so correct! Given the option of 2 (or more) products/services, in my mind, the one with the best documentaiton wins...because it usually means it is the option that is more easy to implement...or at least i can research how to make it the esier option to implement, etc. Good docs for the win!
I got a thumbs up just a few days ago on a Confluence doc I wrote months ago explaining at a very high level what two legacy parts of our software does, from a new hire I have never met or spoken to. That really made my day.