5 ms·

That's not Hugo's problem, that's a problem with Hugo's docs. Something that pretty much all projects, and most big companies, struggle with. There's very few

That's not Hugo's problem, that's a problem with Hugo's docs. Something that pretty much all projects, and most big companies, struggle with. There's very few documentation experts out there. Those who write the docs are either devs who write broken English, or English majors who don't understand a lot of the tech stack. In either case, they usually miss the target persona, and what are the reader's needs. Writing docs is hard :/.

MengerSponge 4y ago
Hot take: The docs are an important part of the product. If you notice that the docs are bad, the product is bad. Docs are hard and thankless, but ¯\_(ツ)_/¯ them's the breaks.
- twodave 4y ago
  I'd even take this hot take up a few more degrees and say the docs quality not only represents the product quality, but also validates it. In other words, you can't know whether your product has a chance of being good unless you're _able_ to write good docs for it.
- speed_spread 4y ago
  Even hotter take, you can have a well documented shit product and it'll be better in a lot of cases than a quality product with no docs.
  - WesternWind 4y ago
    This is true. Docs, re not necessarily considered important features of the product itself but they make a huge difference. Other things that I pay attention to are built-in integrations with other tools, the ability to import and export data, familiarity to users, similarity to existing tools, tutorials that leave users confident, and documentation with examples of use cases are all similar factors.
  - twodave 4y ago
    And if your project is open source and the docs are clear and show good vision, you might even attract folks to come fix your broke-ass code :D
  - manachar 4y ago
    That's pretty much the space Wordpress thrives in, isn't it? How shit the product is for Wordpress is a matter of debate, but the documentation and ecosystem around it is robust enough to make it fairly easy to hack and use/abuse to do what you want it to.
- mxuribe 4y ago
  > ...If you notice that the docs are bad, the product is bad... This right here is so correct! Given the option of 2 (or more) products/services, in my mind, the one with the best documentaiton wins...because it usually means it is the option that is more easy to implement...or at least i can research how to make it the esier option to implement, etc. Good docs for the win!
jerf 4y ago
I'm not a hugo expert, but the two main things that I needed were: 1. An understanding of what variables are available, and where. Hugo nicely collects a lot of useful info but it is difficult to know what it all is and where it is. https://gohugo.io/variables/page/ https://gohugo.io/variables/page/ is a good start but it is difficult to know how these are populated. 2. Hugo is implemented in Go, so under the hood everything is strongly typed. But the Hugo documentation throws that all away and presents the dynamically-typed interface that Go's html templates provides. The problem is, figuring out what anything can do is made very difficult by that. So, ok, I have a .Content or a .Data for this page... but what is that? Is it a string? Is it an object? If so, what can I do with it? I have to experiment to find out, or grep over a couple of templates to figure it out. Honestly if I had to make just one suggestion to the Hugo docs team, it would be, strongly type your entire documentation suite. Tell me what the type of everything is, and the resulting methods/functions I can use it with. (If it's an interface, fine, I don't mean all the maximally static types necessarily.) That wouldn't fix everything, but it would fix the frustration I experience of visiting https://gohugo.io/variables/page/ https://gohugo.io/variables/page/ and still wondering what any of that stuff actually is.
hiAndrewQuinn 4y ago
I've been blessed to have started my career at a place where the docs were surprisingly comprehensive, and I've done my best to carry that torch. My old DevOps team wouldn't have it any other way. I got a thumbs up just a few days ago on a Confluence doc I wrote months ago explaining at a very high level what two legacy parts of our software does, from a new hire I have never met or spoken to. That really made my day.

MengerSponge 4y ago

Hot take: The docs are an important part of the product. If you notice that the docs are bad, the product is bad. Docs are hard and thankless, but ¯\_(ツ)_/¯ them's the breaks.

twodave 4y ago
I'd even take this hot take up a few more degrees and say the docs quality not only represents the product quality, but also validates it. In other words, you can't know whether your product has a chance of being good unless you're _able_ to write good docs for it.
speed_spread 4y ago
Even hotter take, you can have a well documented shit product and it'll be better in a lot of cases than a quality product with no docs.
- WesternWind 4y ago
  This is true. Docs, re not necessarily considered important features of the product itself but they make a huge difference. Other things that I pay attention to are built-in integrations with other tools, the ability to import and export data, familiarity to users, similarity to existing tools, tutorials that leave users confident, and documentation with examples of use cases are all similar factors.
- twodave 4y ago
  And if your project is open source and the docs are clear and show good vision, you might even attract folks to come fix your broke-ass code :D
- manachar 4y ago
  That's pretty much the space Wordpress thrives in, isn't it? How shit the product is for Wordpress is a matter of debate, but the documentation and ecosystem around it is robust enough to make it fairly easy to hack and use/abuse to do what you want it to.
mxuribe 4y ago
> ...If you notice that the docs are bad, the product is bad... This right here is so correct! Given the option of 2 (or more) products/services, in my mind, the one with the best documentaiton wins...because it usually means it is the option that is more easy to implement...or at least i can research how to make it the esier option to implement, etc. Good docs for the win!

jerf 4y ago

I'm not a hugo expert, but the two main things that I needed were: 1. An understanding of what variables are available, and where. Hugo nicely collects a lot of useful info but it is difficult to know what it all is and where it is. https://gohugo.io/variables/page/ https://gohugo.io/variables/page/ is a good start but it is difficult to know how these are populated. 2. Hugo is implemented in Go, so under the hood everything is strongly typed. But the Hugo documentation throws that all away and presents the dynamically-typed interface that Go's html templates provides. The problem is, figuring out what anything can do is made very difficult by that. So, ok, I have a .Content or a .Data for this page... but what is that? Is it a string? Is it an object? If so, what can I do with it? I have to experiment to find out, or grep over a couple of templates to figure it out. Honestly if I had to make just one suggestion to the Hugo docs team, it would be, strongly type your entire documentation suite. Tell me what the type of everything is, and the resulting methods/functions I can use it with. (If it's an interface, fine, I don't mean all the maximally static types necessarily.) That wouldn't fix everything, but it would fix the frustration I experience of visiting https://gohugo.io/variables/page/ https://gohugo.io/variables/page/ and still wondering what any of that stuff actually is.

hiAndrewQuinn 4y ago

I've been blessed to have started my career at a place where the docs were surprisingly comprehensive, and I've done my best to carry that torch. My old DevOps team wouldn't have it any other way. I got a thumbs up just a few days ago on a Confluence doc I wrote months ago explaining at a very high level what two legacy parts of our software does, from a new hire I have never met or spoken to. That really made my day.