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

101–110 of 128 posts

Re: Hugo is awesome, its documentation is not

#101

Post by chipotle_coyote »

evanelias wrote: post #45
jdubb wrote: post #14

Very 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…

No, even with past static site generator experience, it can still be a struggle. I had extremely extensive experience with Movable Type, which was a once-hugely-popular blogging platform / CMS / static site generator. And by "extremely extensive", I mean I worked for the company that made the software, in their Services org which built Movable Type-driven sites for major media partners. Despite this, and also already…

Almost off-topic, but I continue to be mildly surprised that there's so few "modern" blogging platform/site generators that use Movable Type's model: a full user-friendly publishing/admin back end, backed by a database rather than flat files, but still basically generating static files for output. The SSGs that Jekyll arguably led the rise of have still largely stayed in the realm of developer tooling -- edit a directory of flat files and do testing, building and deployment from the command line. There's a few PHP-based systems out there that buck this trend, but they seem to mostly be commercial products pitched at small web design firms (e.g., Kirby, Statamic, Craft).

Re: Hugo is awesome, its documentation is not

#102

Post by andrelaszlo »

shadowgovt wrote: post #98
andrelaszlo wrote: post #28

Earlier quoted context omitted.

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.

Yep, had this problem several times already.

Look at the fancy load balancer, it can do traffic splitting and you can attach a security policy (waf) to it! Oh wait, you can't do traffic management stuff with the "classic" (legacy) LB, switch to the new one that's still in "preview" (beta). Oh wait, it doesn't support the waf yet. Etc etc.

Another one is some sort of hard-coded service users that must be in place to run things, for example in App Engine. If you delete it, you can't just create a new one with the same permissions, you must undelete it... but only if less than 30 days have passed (!).

All of this is documented of course, but spread out all over the place. The thing about deleting service users isn't (as far as I know) made clear in the IAM docs, for example. The only place I found it was in a howto for the App Engine Python environment: "Using the Default App Engine Service Account".

I share the author's frustration, if it isn't obvious :)

Re: Hugo is awesome, its documentation is not

#104

Post by chipotle_coyote »

dahdum wrote: post #82
autarch wrote: post #26

Earlier quoted context omitted.

Instead of "sucks", how about any of these: * My Frustrations with Hugo's Documentation * How Hugo's Documentation Confuses Me and How to Improve It * Why I Don't Like Hugo's Documentation The key thing I've done here in the first three is to reframe the criticism as an _opinion_ ("I", "me", "my") rather than an absolute ("it sucks"). I don't think it's too much to ask people to state their opinions _as opinions_ in…

As written it seems to me the intent of the article is to publicly shame the open source devs who contribute their time and effort into doing more work for free. It's typical open source toxicity.

This makes me think of the old programmer joke that's something like, "There's no documentation. If it was hard to write, it should be hard to understand."

In project like Hugo that has no "user interface" to speak of, tools for which you can't reasonably be expected to just look at the UI screens and figure things out if they're nicely done because there are no UI screens to look at, the documentation is the user interface. Full stop.

The article lays out exactly what its author doesn't like about the documentation and makes suggestions for improvement. The "your documentation sucks" title is the harshest thing about it, and if it was truly a rant I could see getting prickly about it, but it absolutely is not. This is constructive criticism. And that's just as important for an open source project as it is for any other project.

I get bristling at the "if you can't stand having your suggestions torn apart, then don't contribute to open source" weird macho mindset some projects have historically have. Yes, it's toxic. But "if your suggestion is not sufficiently deferential, away with you" goes too far in the other direction.

Re: Hugo is awesome, its documentation is not

#106

Post by lolinder »

abnercoimbre wrote: post #99
earthboundkid wrote: post #88

Earlier quoted context omitted.

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.

Re: Hugo is awesome, its documentation is not

#107

Post by fastaguy88 »

abnercoimbre wrote: post #99
earthboundkid wrote: post #88

Earlier quoted context omitted.

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?

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.

Re: Hugo is awesome, its documentation is not

#108

Post by synergy20 »

I now think rust-based mdbook is simpler and better than hugo, give it a spin. the limit of mdbook is that it's one book only.

another one is vitepress(vue3 based but you don't need know vue3 to use vitepress) that you can have multiple 'books' under one site.

Re: Hugo is awesome, its documentation is not

#109

Post by lolinder »

chipotle_coyote wrote: post #101
evanelias wrote: post #45

Earlier quoted context omitted.

No, even with past static site generator experience, it can still be a struggle. I had extremely extensive experience with Movable Type, which was a once-hugely-popular blogging platform / CMS / static site generator. And by "extremely extensive", I mean I worked for the company that made the software, in their Services org which built Movable Type-driven sites for major media partners. Despite this, and also already…

Almost off-topic, but I continue to be mildly surprised that there's so few "modern" blogging platform/site generators that use Movable Type's model: a full user-friendly publishing/admin back end, backed by a database rather than flat files, but still basically generating static files for output. The SSGs that Jekyll arguably led the rise of have still largely stayed in the realm of developer tooling -- edit a direc…

One of the big reasons I lean toward static sites for my stuff is that you can host them out of an S3 bucket or similar with no dynamic endpoints whatsoever. This is a huge win for security for projects that I don't have time to keep constantly updating. A web-based admin backend largely eliminates that value unless it's run off a separate port that I can firewall, and even then I have to be sure I firewalled it correctly.

There is a space that I'd like to explore, though, and that's having a static site generator that is built into a desktop-based GUI. My dream is to get the brain-dead security of an SSG without having to fiddle about with files and folder structures.

Post reply on HN