Hugo is awesome, its documentation is not
1–10 of 128 posts
Re: Hugo is awesome, its documentation is not
#2While I agree with a lot of the points made, I feel like it overstates the need to "read so many pages". You don't need need to follow each link as soon as its presented, and reading just the discussed page does feel like it gives me a usable starting point, despite that I have never used Hugo, and not read any other documentation pages at this point.
Re: Hugo is awesome, its documentation is not
#3This gives a few good examples of how the Hugo documentation could improve (the click-bait word "Sucks" in the title is a bit exaggerated, in my opinion). I would challenge the author to, in the spirit of open source, go ahead and make some of the suggested changes and submit the changes in a Pull Request!
Re: Hugo is awesome, its documentation is not
#4Thinking 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
Re: Hugo is awesome, its documentation is not
#5It has been quite a while since I ran through some of their getting started stuff. My biggest problem with it is that if you don’t choose a theme the tutorials and guides don’t work. You didn’t get an un-themed vanilla site, you got a bunch of error messages and no HTML.
Having a parallel set of tutorials that do not use a theme would make a large improvement in understanding what is going on.
Re: Hugo is awesome, its documentation is not
#6There are so many ways to title the article and approach this topic, yet the author still chose a petulant and insulting one to vie for attention.
Re: Hugo is awesome, its documentation is not
#7Thinking 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://d…
Love this system.
BTW, I think this might be the updated version of the same site (decoupled from Divio): https://diataxis.fr/
Re: Hugo is awesome, its documentation is not
#8There are so many ways to title the article and approach this topic, yet the author still chose a petulant and insulting one to vie for attention.
I think the title is silly, but the article is reasonable.
I have this same problem with the documentation for the (really absolutely incredibly useful) Caddy webserver.
Caddy itself is extremely powerful and you can do a lot with the configuration. But finding how you do that requires exploring the documentation as if it were a hypertext adventure. Some of this comes from the documentation effort being repeated for the significantly different 2.x version, but it's also a deliberate choice.
Re: Hugo is awesome, its documentation is not
#9Thinking 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://d…
[deleted]
Re: Hugo is awesome, its documentation is not
#10This gives a few good examples of how the Hugo documentation could improve (the click-bait word "Sucks" in the title is a bit exaggerated, in my opinion). I would challenge the author to, in the spirit of open source, go ahead and make some of the suggested changes and submit the changes in a Pull Request!
The author could have saved a paragraph or two of preamble by choosing a less inflammatory title.
No need to write a disclaimer about best intentions unless you chose language that could rile people up.