Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Hugo is awesome, its documentation is not

sagar.se

Post reply on HN
Print view View original

91–100 of 128 posts

Re: Hugo is awesome, its documentation is not

#91

Post by autarch »

systemvoltage wrote: post #53
autarch wrote: post #34

Earlier quoted context omitted.

I don't think the issue is being professional or not. If the author's goal is to convince people who work on Hugo to improve the docs, then it's best to avoid triggering a defensive emotional reaction. The title as it stands will likely trigger hurt feelings, which is usually followed by being defensive or ignoring the substance of the criticism. That's simply unproductive.

The only thing I agree here is that better language wouldn't hurt. I don't think most people get "triggered". That's a vocal minority perpetuating a culture demanding a sort of conformity against their definition of "micro-aggressions" and "triggers" with no regards to a larger consultation with the society.

I didn't use the words "triggered" or "micro-aggressions", so what exactly are you quoting?

Saying "your project sucks" or "your project docs suck" is not a _micro_-aggression, it's a macro-aggression, or as I prefer, being a jerk. I think most people would react negatively to that sort of statement.

Re: Hugo is awesome, its documentation is not

#92

Post by nouveaux »

bojanvidanovic wrote: post #59

From my personal experience, confusing documentation comes from its extreme flexibility which makes a steep learning curve, but once you get your mind around it, it becomes a powerful tool for pretty much anything. Some time ago, I made a very simple blog ( https://devandgear.com ) in Hugo, which eventually with time evolved into a much bigger and more complex website (>2000 pages), that evolvement was possible thank…

> confusing documentation comes from its extreme flexibility which makes a steep learning curve, but once you get your mind around it, it becomes a powerful tool for pretty much anything

I have not used Hugo and I have no idea how powerful it is but I am quite skeptical. It's hard for me to believe that it is more powerful and flexible than Django and Django's documentation is very good.

Re: Hugo is awesome, its documentation is not

#94

Post by mholt »

StevenWaterman wrote: post #4

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://d…

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

Re: Hugo is awesome, its documentation is not

#95

Post by qbasic_forever »

azangru wrote: post #61

As a web developer, primarily on the front end, all I can say these days is: Eleventy.

Yeah, I wish there were a go version of the same minimal template engine/swiss army knife that is eleventy. Hugo is nice if you need some full fledged CMS workflow and can do everything the hugo way. But IMHO if you're just turning some markdown into HTML with a simple template then hugo has far too many concepts and abstractions. Eleventy is a breath of fresh air and can be learned and made productive in an afternoon.

Re: Hugo is awesome, its documentation is not

#96

Post by jordanmorgan10 »

For this precise reason, I use Jekyll. I got so frustrated with Hugo, and when I went to Jekyll they had an entire "From start to finish, make a blog with Jekyll" in their docs.

That made all of the difference for me.

This was about 3 years ago, so maybe things have changed. But last time I checked, Jekyll still had that guide up.

Re: Hugo is awesome, its documentation is not

#97

Post by remoquete »

_jal wrote: post #23
StevenWaterman wrote: post #4

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://d…

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…

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

Re: Hugo is awesome, its documentation is not

#98

Post by shadowgovt »

andrelaszlo wrote: post #28
PaulHoule wrote: post #12

It'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 programmi…

I'm working a bit with GCP infrastructure lately and I find Google's docs very well-written, but suffering from a bit of the opposite problem. Many docs are written as how-tos for very specific scenarios, often the most basic setup thinkable (which makes sense!). If you're trying to understand the abstractions in order to see what will make sense for your own project, it's a difficult way to get the full picture. :D…

The problem Google runs into is a lot of the systems they build in GCP are written that way too: with a specific set of user-stories in mind, and an "I guess we'll see what the community does with it" attitude for any use cases they didn't anticipate.

This might be a symptom of the problem domain itself.

Re: Hugo is awesome, its documentation is not

#99

Post by abnercoimbre »

earthboundkid wrote: post #88
rsolva wrote: post #29

Earlier quoted context omitted.

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…

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?

Post reply on HN