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

41–50 of 128 posts

Re: Hugo is awesome, its documentation is not

#41

Post by teach »

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…

There are, in fact, four types of documentation[0]:

1. Tutorials 2. How-To Guides 3. Explanation 4. Reference

[0] https://documentation.divio.com/

Edit: and of course this is a top-level comment down below.

Re: Hugo is awesome, its documentation is not

#43

Post by zellyn »

chrisbrandow wrote: post #32

As someone who is a competent iOS developer but not much of a web developer, all I can say is that I completely identify with this critique. The Hugo docs are just straight to the deep end.

As someone who is an experienced back-end developer, and used Hugo quite early on, and has understood enough of the Hugo/Goldmark integration to write and install a custom markdown plugin, all I can say is that I _completely identify_ with this critique.

I would add:

    - the ecosystem of Hugo theme production/rating seems SEO-scammy
    - the docs seem uncertain on whether you should use “Modules”
That said, I was able to hack pikchr.org support into my blog, and the ability to create beautiful diagrams[1] while previewing with live refresh has been amazing.

[1] eg: https://zellyn.com/2022/02/cs-ramble/1c/

Re: Hugo is awesome, its documentation is not

#44

Post by rsolva »

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

Love this system. BTW, I think this might be the updated version of the same site (decoupled from Divio): https://diataxis.fr/

Thank you for the link, this system really deserves its own dedicated website :)

Re: Hugo is awesome, its documentation is not

#45

Post by evanelias »

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 having Golang html/template experience, Hugo's docs and concepts were still very difficult for me to learn!

Re: Hugo is awesome, its documentation is not

#47

Post by svnpenn »

adriangrigore wrote: post #40
svnpenn wrote: post #30

Earlier quoted context omitted.

> using sh as a templating language. You should probably explain what "sh" is. It may seem obvious to you, but not to everyone. Something like: > using POSIX shell "sh" as a templating language. (hopefully youre using POSIX?). Also, where is the source code? I see this: https://mkws.sh/mkws@4.0.16.tgz but do you really not use version control?

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?

Re: Hugo is awesome, its documentation is not

#49

Post by PaulHoule »

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…

Ideal documentation has interlinked sections that serve different purposes.

For instance right now I am writing up a report on a research project I did a year ago (shouldn't have waited) and now facing the problem of running the scripts. Some of them are well documented but some aren't. Whether it is you or somebody in your pod who has to do it, there is a need for "runbook" documentation so you can do tasks such as building and deploying software correctly and easily.

There's also a need for reference documentation that explains everything systematically, even that tends to need multiple forks -- for the Spring framework there is all of the Javadocs, but the Javadocs are not sufficient to explain the concepts that Spring is built around.

Then there are the pedagogical examples that make doing something tricky look easy and link the implementation to the concepts involved.

I'd point to the Python documentation as a particularly good example. I never feel tempted to look outside the official Python documentation to look up anything that's involved in the core language.

Somehow I don't find the documentation for pandas to be effective, largely because I perceive the ways of doing things in pandas to be idiosyncratic, so I find myself looking up answers on random web sites a lot more often than I feel comfortable with. If I used pandas everyday I might feel differently, but I usually end up doing a burst of data analysis work for a few days and then go a few months w/o using pandas.

Re: Hugo is awesome, its documentation is not

#50

Post by wink »

svnpenn wrote: post #21
atishay811 wrote: post #17

Hugo’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.

> Hugo’s documentation is a great reference and very well articulated No its not, and not its not. Hugo it easy to install and/or build, I will give it that. But the documentation has always been poor in my mind, with gaping holes for common uses that are maybe outside of the opinionated "norms".

It's been a while, but I'd sum it up as:

I want to do A, B, C. Now I need to find out how A,B,C are called in hugo, how they relate to each other, which mandatory concepts D,E they depend on, how those relate to each other and then, if everything would be perfectly written, I might understand it.

I actually think it's a good reference. If you know what an archetype is and what you can do with it, just forgot the syntax? Bingo. To grasp what its good for? Not so much.

Maybe if someone collected a bunch of actual problems of "How do I ...?" and made them into a really good FAQ, that might help?

That said, I also don't have a solution - I think they've succumbed to feature creep a little too much. In the quest to let every non-programmer be able to tweak every single thing, now the non-programmer needs to learn a DSL.

Post reply on HN