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

21–30 of 128 posts

Re: Hugo is awesome, its documentation is not

#21

Post by svnpenn »

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".

Re: Hugo is awesome, its documentation is not

#22

Post by digianarchist »

andrelaszlo wrote: post #19

One 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 think the post serves as general advice for writing documentation for a project. If the author had gone off and wrote docs for Hugo they 1. Might not have been accepted 2. Wouldn't contain info on why the docs are bad.

Re: Hugo is awesome, its documentation is not

#23

Post by _jal »

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, but I did get to see an amazing kerfluffle when an innocent question about an old feature everyone except the tech writers forgot about ended up derailing a release while people figured out how to reconcile things.

Completely aside from function, really good technical documentation is just a joy to read and use. It is sad that "we" produce far less of it than we used to.

Re: Hugo is awesome, its documentation is not

#24

Post by oauea »

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…

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

I like opening such docs twice. The first to read through, and the second to search for more info about what I'm currently reading.

Re: Hugo is awesome, its documentation is not

#26

Post by autarch »

systemvoltage wrote: post #15
ljm wrote: post #10

Earlier quoted context omitted.

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. 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 cases where you know in advance that said opinion may lead to hurt feelings. These titles might _still_ lead to hurt feelings, but I think they're less likely to do so, and if they do then they will hurt less.

Re: Hugo is awesome, its documentation is not

#27

Post by PaulHoule »

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

> 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. I like opening such docs twice. The first to read through, and the second to search for more info about what I'm currently reading.

That's a good idea. Sometimes you need to explore (build your understanding of the concepts behind the system) and sometimes you need to exploit (get the answer for one particular problem).

Re: Hugo is awesome, its documentation is not

#28

Post by andrelaszlo »

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

It seems like good docs often have two types of articles:

1. Short and clear definitions of terms, abstractions, resources, etc. 2. Self-contained how-tos and overview type articles on common issues and ways to use the product.

If it's just one or the other, or both mixed up, I often find it frustrating.

Re: Hugo is awesome, its documentation is not

#29

Post by rsolva »

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…

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.io/t/feature-overall-ease-of-use/34...

Re: Hugo is awesome, its documentation is not

#30

Post by svnpenn »

adriangrigore wrote: post #20

Feedback on my static site generator's documentation if we're here? :D https://mkws.sh/docs.html

> 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?

Post reply on HN