4 ms·
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 fou
by StevenWaterman 5y ago
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/ https://documentation.divio.com/
- chatmasta 5y agoLove this system. BTW, I think this might be the updated version of the same site (decoupled from Divio): https://diataxis.fr/ https://diataxis.fr/
- rsolva 5y agoThank you for the link, this system really deserves its own dedicated website :)
- deleted 5y ago[deleted]
- aae42 5y ago> 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/ 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
- _jal 5y agoAside 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.
- remoquete 5y agoThis. No matter what fancy docs framework or system you use, you need people dedicated to the craft.
- rsolva 5y agoI 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/34732 https://discourse.gohugo.io/t/feature-overall-ease-of-use/34...
- earthboundkid 5y agoI 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-scratch-the-absolute-minimum/35510 https://discourse.gohugo.io/t/discussion-of-hugo-theme-from-... I think the problem is just that no one wants to bell the cat. :-(
- apprewired 5y agoI 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!
- abnercoimbre 5y ago> 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?
- lolinder 5y agohttps://en.wikipedia.org/wiki/Belling_the_Cat 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.
- mholt 5y agoThis 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/ https://caddyserver.com/docs/ [2]: https://caddy.community/c/wiki/13 https://caddy.community/c/wiki/13