It sounds like a basic thing, but it's also the main reason people write bad documentation
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.
(We also get a lot of feedback about what they're lacking which we are working on; but I wanted to point out that we do try to keep to those 4 main categories and it works well. Plus a wiki [2] where people can contribute examples.)
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...
I think the problem is just that no one wants to bell the cat. :-(
BTW, I think this might be the updated version of the same site (decoupled from Divio): https://diataxis.fr/
i think you've hit on something here
i read docs like this: https://gohugo.io/templates/lookup-order/ which are incredibly useful, but i end up using it as a reference... hugo docs could use a run-through and re-org w/ the divio principles in mind
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.
The whole "They Are Just Go Templates" is a pretty pathetic cop out. Sorry, but it's true. If I'm trying to use Hugo, I don't want to be digging in Go docs at the same time, and as you point out, you can't know things like scopes and what Go variables might actually be available.
And yes, most of the actual syntax is simply not documented.
I subsequently gave up on Hugo entirely and ported my Hugo sites to Next.js, which is in fact documented--and can work well with TypeScript, so complex pages are fully strongly typed, which makes work in an IDE a breeze.
Reading the docs lead me to believe that the templates were invented by Hugo. It would of been helpful to make the distinction because I could have looked up how the templates work. I'm not sure if it would have helped though because Go's templates are incredibly confusing and frustrating to use.
Every time I restructure how I do my personal website I get a strong urge to sit down and write a more disciplined static website generator. (Don't worry. I won't. I don't have that kind of spare time on my hands). Obviously one that has fewer degrees of freedom so as to make theming meaningfully possible. Because Hugo themes aren't really themes. They are more like applications where your website probably isn't going to work without a lot of hacking.
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 programming splogs and StackOverflow and by the time you find a hugo that's been worked on for 3 years there is no rhyme or reason for how things are done because nobody has ever understood how hugo works and now you can't fix anything without risking massive breakage.
I am going through this right now with a project that I may wind up doing with hugo. On one hand I can make the case that hugo is good for my case but I can also say that I'd be happier customizing a Python-based solution or that I think the markup in hugo is less than optimal (I guess I can do anything with shortcodes but I'd really like to do visualization and unique typography in some ways... I don't want to make something that looks like a second rate substack.)
I haven't had the heart for a real battle against circularity by reading the documentation and with no definite deadline to get my hugo site up I find that other projects are tempting to think about instead...
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.
* Tutorials * Topic guides * Reference guides * How-to guides
https://docs.djangoproject.com/en/4.0/#how-the-documentation...
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.
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.
This might be a symptom of the problem domain itself.
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.
It's a very toxic thing that Spring wasted it's brand to endorse a bunch of thin low quality packages.
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.
Having a parallel set of tutorials that do not use a theme would make a large improvement in understanding what is going on.
Perhaps it's expected that when you use Hugo, you already recognize most concepts from other static site generators?
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!
It was ignored for over a year, with the only comment being from me, then automatically marked stale and closed.
Needless to say I didn't open any additional PRs.
Also, this reflects my impression of the Hugo community in general - their discourse forum is pretty dismissive to questions (lots of "have you read the docs?" type responses when yes, I did read the damn docs, found them utterly confusing and that's why I spent 20 minutes writing up a detailed forum post to ask for advice).
I think the stale bot in Hugo repo is overly aggressive. I have had to "fight" the stalebot in the past by posting update messages.
No need to write a disclaimer about best intentions unless you chose language that could rile people up.
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.
People these days have an adverse reaction to any sort of criticism and it is troubling. Anything other than a pat on the back and emojis is considered rude. We got rid of downvotes on YouTube and this was the justification.
The Hugo docs are just straight to the deep end.
I would add:
- the ecosystem of Hugo theme production/rating seems SEO-scammy
- the docs seem uncertain on whether you should use “Modules”
To give a concrete example, I spent quite a while just figuring out what it means to put a piece of content into a directory under hugo, and I still don't have a full grasp on it, honestly. What does it mean to put something under "content/posts/2011" versus dumping it into content/posts? How exactly do categories and tags get populated? (What is the difference between them?)
Something as basic as that has taken me quite a while to get through.
(Please note I am not asking for answers to those questions here. In fact dumping the answers here in a nice, clean, easy-to-understand format that walks you through from start to finish would be in some sense actively counterproductive. Go dump them in the Hugo docs!)
I can not point you at a specific page that describes the answer to this question.
I can not point you at a specific page that describes how we get from content to the various collections of content. This documentation exists, but it's buried in a generic listing that has tons of other stuff, and IIRC still doesn't describe edge cases; I was experimenting with things just to see what they did, because I don't think the docs even acknowledged the edge case. Also, there's a lot of stuff made available in the templates but there's nothing like type-level documentation that says what is of what type and what that type can do; collections of pages will be described almost literally as that, but with no link to exactly what a Page object is. Again, it's probably all there somewhere but it's very hard to use.
I mean, technically it's all there, but I certainly had to go on an adventure to get it all.
The tutorial also suffers from being too simplified. Tutorials always have this temptation to show off all the magic being used in its simplest possible default configuration, which is fine, but then if you want something other that the simplest possible default configuration you're left with not much to go on.
It could be worse, but it certainly has some organizational problems. No matter what problem I come the documentation with, be it looking up what an API does, trying to understand a subsystem, understanding the whole thing holistically, figuring out why I want a certain feature (I almost manually recreated the entire concept of a manual taxonomy before figuring out what it actually meant), the docs just never quite manage to answer my question.
The docs are written almost entirely in the first context, building the concepts up and explaining how they work together, so if you start with the docs you can end up spending a lot of time trying to create a mental model entirely out of these concepts, with no connection to the concrete function of the software.
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.
https://pragprog.com/titles/bhhugo/build-websites-with-hugo/
I do hear the concerns here. I agree that the docs are more reference style, and less tutorial style. (Tho, as you gain experience, you prefer the reference style).
After I learned hugo, I wrote the tutorial I wish I would of had. Am shamelessly sharing it here in case it's useful for someone else wanting to deep dive:
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 wonder how useful this type of feedback is, and if the irritation over the docs could have been challenged into something more impactful.
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".
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.
> 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.
Also helps with the urge to tweak things instead of writing (not that I write much anyways).
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.
Here is my wife site [1] with custom Call me Sam theme [2]. Check it out and let see what a hardware designer can do for his wife :)
It's super convenient to have autocomplete, syntax highlighting and everything that comes with it.
If Hugo could have that too, I'd go for it in a second.
I have not used Hugo and I have no idea how powerful it is but I am quite skeptical. It's hard for me to believe that it is more powerful and flexible than Django and Django's documentation is very good.
But, (a) it's preprint and has copy-editing bugs and (b) it doesn't address the issue of the lack of reference docs.
Is the competition better? I see a lot of buzz around eleventy. There's also Pelican, Jekyll, Gatsby and many others.
That made all of the difference for me.
This was about 3 years ago, so maybe things have changed. But last time I checked, Jekyll still had that guide up.
Add ability to generate per-{year, month, day} archives: https://github.com/gohugoio/hugo/issues/448
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?
> 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
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 the significantly different 2.x version, but it's also a deliberate choice.
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
A few years ago I tried using Hugo and it felt like the docs were made for people who already knew how it worked. After all, it's very hard to write docs from the eyes of someone who doesn't even know what the jargon is and why the various concepts exist. As a newcomer, you end up saying a lot of "okay, but what is a practical example of how this helps me?" as you scuttle through a bunch of browser tabs.
At least back when I tried it, Hugo could use a guide like https://reactjs.org/tutorial/tutorial.html that builds up a website from the basics while incrementally using Hugo features to solve problems with a toy website like, say, e-shop product pages to show how things fit together.