I can sympathize with the author. I once attempted Hugo and gave up after a few hours and proceeded with vanilla PHP, which for most contexts is better and easier than any static site generator.
Hugo is awesome, its documentation is not
11–20 of 128 posts
Re: Hugo is awesome, its documentation is not
#12It's a problem with most systems that introduce a number of new concepts, such as the documentation for the Spring framework.
One answer as a reader to deal with the circularity by reading the documentation and then reading the documentation again and then read it again until you know where everything is and then you look it up.
The worst thing about this situation is that people go look up wrong answers on programming splogs and StackOverflow and by the time you find a hugo that's been worked on for 3 years there is no rhyme or reason for how things are done because nobody has ever understood how hugo works and now you can't fix anything without risking massive breakage.
I am going through this right now with a project that I may wind up doing with hugo. On one hand I can make the case that hugo is good for my case but I can also say that I'd be happier customizing a Python-based solution or that I think the markup in hugo is less than optimal (I guess I can do anything with shortcodes but I'd really like to do visualization and unique typography in some ways... I don't want to make something that looks like a second rate substack.)
I haven't had the heart for a real battle against circularity by reading the documentation and with no definite deadline to get my hugo site up I find that other projects are tempting to think about instead...
Re: Hugo is awesome, its documentation is not
#13Thinking 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…
> 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
Re: Hugo is awesome, its documentation is not
#14Very recognizable. I've used Hugo for exactly one website, as a first introduction to static site generators. The site still runs, and if I need to change something running the `hugo` CLI still works. But it wasn't easy to get started, with all these new concepts, and this site explains clearly the trouble I had.
Perhaps it's expected that when you use Hugo, you already recognize most concepts from other static site generators?
Re: Hugo is awesome, its documentation is not
#15This 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.
How would you suggest to write a title that’s less inflammatory?
I have a higher tolerance to this type of language. Some people find any critique offensive. Some embrace it.
With any public confrontation, you’re bound to get a spectrum of people with various reactions. How do we make sure criticism, even harsh, needs space in public dialog whether it is open source or not? If it’s meant with good faith, that is.
People these days have an adverse reaction to any sort of criticism and it is troubling. Anything other than a pat on the back and emojis is considered rude. We got rid of downvotes on YouTube and this was the justification.
Re: Hugo is awesome, its documentation is not
#16To the author: I love that you use different formatting to break up your page, but I also recommend breaking up some of your paragraphs, as they are a little dense.
Re: Hugo is awesome, its documentation is not
#17Hugo’s documentation is a great reference and very well articulated. If you are looking for a tutorial and want to grow understanding, a book might be much better. I am the author of Hugo In Action (https://hugoinaction.com) and the objective of my book is to introduce the concepts slowly and with a running example for easily trying out.
Re: Hugo is awesome, its documentation is not
#18While 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.
I know what they are talking about.
A few years ago I tried using Hugo and it felt like the docs were made for people who already knew how it worked. After all, it's very hard to write docs from the eyes of someone who doesn't even know what the jargon is and why the various concepts exist. As a newcomer, you end up saying a lot of "okay, but what is a practical example of how this helps me?" as you scuttle through a bunch of browser tabs.
At least back when I tried it, Hugo could use a guide like https://reactjs.org/tutorial/tutorial.html that builds up a website from the basics while incrementally using Hugo features to solve problems with a toy website like, say, e-shop product pages to show how things fit together.
Re: Hugo is awesome, its documentation is not
#19One good way to understand how something works is to write documentation for it. In this case it seems like the author has pretty strong opinions about how it should be done. It's a big job, of course, but perhaps similar in effort to writing a blog post?
I don't mean to be snarky! Just got the feeling that the current docs are written a bit as an afterthought and that the blogger, on the other hand, is a good writer. I wonder how useful this type of feedback is, and if the irritation over the docs could have been challenged into something more impactful.
Re: Hugo is awesome, its documentation is not
#20Feedback on my static site generator's documentation if we're here? :D https://mkws.sh/docs.html