Hacker News Reader

Comment by StevenWaterman | Hacker News Reader

Thinking about the four kinds of documentation [1], it seems like the Hugo docs are structured as a reference but presented as an explanation/tutorial. I've found it useful to sit down and explicitly think about the purpose of a piece of documentation before writing it, and then write it with that purpose in mind.

It sounds like a basic thing, but it's also the main reason people write bad documentation

[1] https://documentation.divio.com/

View on HN

Aside from the general lack of quality documentation these days, the decline of technical writing as a profession has been a big loss.

They didn't just organize and write documentation. I recall doc interviews where tech writers would quiz me on how something worked, and on more than one occasion pointed out problems that sat at the intersection of functionality and UI that everyone else missed. And not my department, but I did get to see an amazing kerfluffle when an innocent question about an old feature everyone except the tech writers forgot about ended up derailing a release while people figured out how to reconcile things.

Completely aside from function, really good technical documentation is just a joy to read and use. It is sad that "we" produce far less of it than we used to.

This. No matter what fancy docs framework or system you use, you need people dedicated to the craft.

This is what we've tried to do with the Caddy docs [1]. We get a lot of compliments about how easy they are to navigate and access, and how useful they are.

(We also get a lot of feedback about what they're lacking which we are working on; but I wanted to point out that we do try to keep to those 4 main categories and it works well. Plus a wiki [2] where people can contribute examples.)

[1]: https://caddyserver.com/docs/

[2]: https://caddy.community/c/wiki/13

I have brought up this exact point on the Hugo forum before [0]. Hugo would become much more accessible if the documentation would be split into the four categories mentioned in the link you provide.

This way of thinking about documentation should be the default, and any open source project (or closed for that matter) would benefit hugely by adhering to these simple principles!

0: Discussion: https://discourse.gohugo.io/t/feature-overall-ease-of-use/34...

I tried to start a discussion about documentation as reference vs. tutorials on the forums too: https://discourse.gohugo.io/t/discussion-of-hugo-theme-from-...

I think the problem is just that no one wants to bell the cat. :-(

> no one wants to bell the cat. :-(

Never heard this refrain before! What does it mean? No one wants to get on leadership's bad side?

https://en.wikipedia.org/wiki/Belling_the_Cat

> Belling the Cat is a fable ... In the story, a group of mice agree to attach a bell to a cat's neck to warn of its approach in the future, but they fail to find a volunteer to perform the job. The term has become an idiom describing a group agreeing to perform an impossibly difficult task.

Of course a quick web search answers your question. The fable is that all the mice would like to have the cat wear a bell, but despite the obvious benefits, there are no volunteers for the dangerous task.

I really like the saying 'bell the cat' as well. Anyway, came here to say that I started to do this (create the missing documentation that would've been helpful for me) - it is by no means ready ( on mobile this site looks almost unreadable ) but it is a start: www.hugotutorial.com - if you have any feedback, I would love it!

Love this system.

BTW, I think this might be the updated version of the same site (decoupled from Divio): https://diataxis.fr/

Thank you for the link, this system really deserves its own dedicated website :)

> structured as a reference but presented as an explanation/tutorial

i think you've hit on something here

i read docs like this: https://gohugo.io/templates/lookup-order/ which are incredibly useful, but i end up using it as a reference... hugo docs could use a run-through and re-org w/ the divio principles in mind

Reply on news.ycombinator.com