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

51–60 of 128 posts

Re: Hugo is awesome, its documentation is not

#51

Post by PaulHoule »

dmitriid wrote: post #39
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…

> such as the documentation for the Spring framework. Oh god, so true. It doesn't help when it's not a single project, but fifteen hundred different projects (as is the case with spring) and it's impossible to find a coherent documentation beyond the most basic examples.

My attitude is that everything other than the core framework is crap. That is, spring-your-life-wouldnt-be-meaningful-without-this-set-of-broken-abstractions-for-some-api inevitably makes your life worse than directly engaging the API with Spring or building spring-correct-abstraction-for-api yourself.

It's a very toxic thing that Spring wasted it's brand to endorse a bunch of thin low quality packages.

Re: Hugo is awesome, its documentation is not

#52

Post by rsolva »

This quote from the conclusion sums up my personal experience with Hugos docs:

> The thing is, after having spent a lot of time tinkering with Hugo, I have now assimilated enough knowledge that the existing Hugo docs make perfect sense…most of the time. Maybe this is the case with other users of Hugo too. However, I still remember how frustrating it felt while reading the docs for the first time.

Re: Hugo is awesome, its documentation is not

#53

Post by systemvoltage »

autarch wrote: post #34
systemvoltage wrote: post #31

Earlier quoted context omitted.

Those are all great suggestions and that’s what I would use. However, if you look under the facade, when talking to your colleagues and with people around you, “sucks” is very much a common, daily word. This is the way I look at it. Sure, it’s not professional. But, the author is not trying to be professional I suppose. I am not going to debate it’s appropriateness. I want to be clear, the point I’m debating is not a…

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.

Re: Hugo is awesome, its documentation is not

#54

Post by corobo »

autarch wrote: post #26
systemvoltage wrote: post #15

Earlier quoted context omitted.

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. Peo…

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…

It's a shame we can't peek into alternate universes to prove/disprove but I have to imagine those titles wouldn't have nearly as many upvotes

Re: Hugo is awesome, its documentation is not

#55

Post by throwaway284534 »

My most frustrating experience with Hugo is their template language and lack of clear explanations, often waiving away any complexities as, “They’re just Go templates.” Fair enough, but the docs make no attempt to explain how scoping works, how variables can be applied to partials, or even how to construct a simple for-loop. There’s an answer for each of these problems but implementing a full solution requires scouring through the Go docs and Hugo’s own forums for a complete and pragmatic solution.

I had a heck of a time with Hugo’s concept of “Scratch” while generating a breadcrumb navigation. Combined with a JSON schema, Google will include these crumb segments in search results. But much like Handlebars, Go template expressions aren’t REPL friendly, and a the learning experience involves a lot of refreshing and debug output just to get a clue as to how things work.

Personally, this has bitten me with every “stringly” typed template language. IDE’s have little information to work with, and much like playing a game of Wordle, you’re left to fill in the blanks — one line at a time.

Re: Hugo is awesome, its documentation is not

#56

Post by corobo »

unfocussed_mike wrote: post #8
dahdum wrote: post #6

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

Caddy's 2.x documentation almost put me off Caddy haha

Try to find how to use the `ask` function to verify whether a requested domain should get a certificate provisioned.

If you can do it without having to manually sift through the docs and then give up and tackle it with trial and error I'll.. well I'll be put in my place, but it proper tripped me up when I needed it

Re: Hugo is awesome, its documentation is not

#57

Post by adriangrigore »

svnpenn wrote: post #47
adriangrigore wrote: post #40

Earlier quoted context omitted.

Not sure if people who understand > POSIX Shell "sh" don't understand > sh Thanks for the suggestion! Yes, it's certainly POSIX, I don't use version control now, I run a back up cron every 30 minutes. Playing around without git. Sources: https://mkws.sh/docs.html#sources

Where are the previous versions?

They're not listed, good idea to list them somewhere.

Re: Hugo is awesome, its documentation is not

#58

Post by karaterobot »

I remember making the case to spend a few days to testing out Hugo as an alternative to Jekyll for our company's website. At that time, about 3 years go, I bounced off this documentation pretty hard as well. It does not appear to have improved significantly, which is a shame.

On the other hand, I now know that, in cases like this, you'd go watch some video tutorials before going back to the documentation armed with enough conceptual knowledge to maybe prime the pump and make that cryptic documentation start to fall into place (lots of mixed metaphors there). You shouldn't have to, but it's nice that there's the option.

Re: Hugo is awesome, its documentation is not

#59

Post by bojanvidanovic »

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 thanks to its wide array of tools otherwise it would require a different builder.

Re: Hugo is awesome, its documentation is not

#60

Post by rr808 »

throwaway284534 wrote: post #55

My most frustrating experience with Hugo is their template language and lack of clear explanations, often waiving away any complexities as, “They’re just Go templates.” Fair enough, but the docs make no attempt to explain how scoping works, how variables can be applied to partials, or even how to construct a simple for-loop. There’s an answer for each of these problems but implementing a full solution requires scouri…

I've had the same issue with Helm Templates - "they're just Go templates".
Post reply on HN