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
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.
This is what we've tried to do with the Caddy docs [1]. We get a lot of compliments about how easy they are to navigate and access, and how useful they are.
(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.)
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!
> Belling the Cat is a fable ... In the story, a group of mice agree to attach a bell to a cat's neck to warn of its approach in the future, but they fail to find a volunteer to perform the job. The term has become an idiom describing a group agreeing to perform an impossibly difficult task.
Of course a quick web search answers your question. The fable is that all the mice would like to have the cat wear a bell, but despite the obvious benefits, there are no volunteers for the dangerous task.
I really like the saying 'bell the cat' as well. Anyway, came here to say that I started to do this (create the missing documentation that would've been helpful for me) - it is by no means ready ( on mobile this site looks almost unreadable ) but it is a start: www.hugotutorial.com - if you have any feedback, I would love it!
> structured as a reference but presented as an explanation/tutorial
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
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.
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.
I agree with you completely about the templates. When I first used Hugo I was not well versed in Go, nor did I have any idea how it's templating system worked.
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.
If something is a pain in the ass to document, it is probably not very clear. Hugo has a bit too much implicit magic that feels unnecessary. It wouldn't have killed us users if things were a bit more explicit.
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.
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 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...
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.
Sphinx has a nice facility for blending "Javadoc" style documentation with discursive explanations which is used to great effect in the Python docs, but used that way it doesn't automatically generate all of the automatically generatable documentation the way Javadoc does so often you end up with lots of content missing.
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.
The problem Google runs into is a lot of the systems they build in GCP are written that way too: with a specific set of user-stories in mind, and an "I guess we'll see what the community does with it" attitude for any use cases they didn't anticipate.
This might be a symptom of the problem domain itself.
Look at the fancy load balancer, it can do traffic splitting and you can attach a security policy (waf) to it! Oh wait, you can't do traffic management stuff with the "classic" (legacy) LB, switch to the new one that's still in "preview" (beta). Oh wait, it doesn't support the waf yet. Etc etc.
Another one is some sort of hard-coded service users that must be in place to run things, for example in App Engine. If you delete it, you can't just create a new one with the same permissions, you must undelete it... but only if less than 30 days have passed (!).
All of this is documented of course, but spread out all over the place. The thing about deleting service users isn't (as far as I know) made clear in the IAM docs, for example. The only place I found it was in a howto for the App Engine Python environment: "Using the Default App Engine Service Account".
I share the author's frustration, if it isn't obvious :)
> 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.
It's been years since I've using Spring. Everybody who pays me to work in Java has used Guava for a while. Most of what I do on my own account is in Python or C (yuck!) or AVR8 assembler. The one Java project I am working on for myself uses balls-to-the-walls metaprogramming and code generation and is designed to enable even more metaprogramming and code generation and doesn't need dependency injection.
I spent a lot of time learning Spring in the day and I felt it filled a gap in Java in a way Guava really doesn't. I call it "configuration driven development". I was writing a large series of report generators in Python and all of them had the structure of "a little script that assembles a few objects in a library together to do a task". In the case of Java that "script" is naturally a Java class that needs to be compiled, goes through the build process, involves artifact management, etc. It's very nice that Spring provides a "general configuration file" that lets you patch together a few objects without having to compile anything.
> 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).
It has been quite a while since I ran through some of their getting started stuff. My biggest problem with it is that if you don’t choose a theme the tutorials and guides don’t work. You didn’t get an un-themed vanilla site, you got a bunch of error messages and no HTML.
Having a parallel set of tutorials that do not use a theme would make a large improvement in understanding what is going on.
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 generators?
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!
Almost off-topic, but I continue to be mildly surprised that there's so few "modern" blogging platform/site generators that use Movable Type's model: a full user-friendly publishing/admin back end, backed by a database rather than flat files, but still basically generating static files for output. The SSGs that Jekyll arguably led the rise of have still largely stayed in the realm of developer tooling -- edit a directory of flat files and do testing, building and deployment from the command line. There's a few PHP-based systems out there that buck this trend, but they seem to mostly be commercial products pitched at small web design firms (e.g., Kirby, Statamic, Craft).
One of the big reasons I lean toward static sites for my stuff is that you can host them out of an S3 bucket or similar with no dynamic endpoints whatsoever. This is a huge win for security for projects that I don't have time to keep constantly updating. A web-based admin backend largely eliminates that value unless it's run off a separate port that I can firewall, and even then I have to be sure I firewalled it correctly.
There is a space that I'd like to explore, though, and that's having a static site generator that is built into a desktop-based GUI. My dream is to get the brain-dead security of an SSG without having to fiddle about with files and folder structures.
Lektor, a Python-based SSG that I've used in the past, actually had a self-contained Mac app for a while that was maybe 75% of the way toward that. (IIRC, the app didn't let you edit templates and most site-level configuration; the idea was more that you got things set up in a more programmer-nerd way first and then used the app for site maintenance/deployment.) Unfortunately, the app broke a few years back and nobody left developing Lektor seems motivated to fix it.
I've seen one other SSG that has an app, Publii, but I've never used it. My impression is that it wasn't as full-featured as Lektor, which could be made to do a lot of neat things. Although if Publii's app still works, that's one big thing Lektor doesn't have, so... :P
This gives a few good examples of how the Hugo documentation could improve (the click-bait word "Sucks" in the title is a bit exaggerated, in my opinion). I would challenge the author to, in the spirit of open source, go ahead and make some of the suggested changes and submit the changes in a Pull Request!
I have actually opened a pull requests [1] on the Hugo docs, adding one small sentence to clarify something that I was stuck on for several hours.
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).
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.
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.
* 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.
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 about “sucks” per se, but any general criticism. Whenever you need disclaimers, it could mean two things 1) Rude or unacceptable title 2) Society expects unreasonable conformity and adherence to a particular language, set of values, etc.
In the case 2), we had a huge debate about “master vs main” branch. There are many examples.
We’d be better off dialing down the conformity and be more inclusive. Check in deeper about intentions and faith, than the facade of language. If the author used the language you suggested, but had bad intentions, that’s a bigger problem.
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.
As written it seems to me the intent of the article is to publicly shame the open source devs who contribute their time and effort into doing more work for free.
This makes me think of the old programmer joke that's something like, "There's no documentation. If it was hard to write, it should be hard to understand."
In project like Hugo that has no "user interface" to speak of, tools for which you can't reasonably be expected to just look at the UI screens and figure things out if they're nicely done because there are no UI screens to look at, the documentation is the user interface. Full stop.
The article lays out exactly what its author doesn't like about the documentation and makes suggestions for improvement. The "your documentation sucks" title is the harshest thing about it, and if it was truly a rant I could see getting prickly about it, but it absolutely is not. This is constructive criticism. And that's just as important for an open source project as it is for any other project.
I get bristling at the "if you can't stand having your suggestions torn apart, then don't contribute to open source" weird macho mindset some projects have historically have. Yes, it's toxic. But "if your suggestion is not sufficiently deferential, away with you" goes too far in the other direction.
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.
As someone who is(was?) a competent web developer, all I can say is that Hugo templating turned me off of the project. For as long as I used Hugo, I felt like I was in a horror corn maze.
I recently started using Hugo for a few websites. I endorse this.
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.
As another poster said, the problem is that Hugo is built around a number of new concepts. To understand them, you have to understand their relation to two contexts: the other Hugo concepts that they are designed to work with, and Hugo's purpose of generating web sites from data.
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.
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.
I like Hugo quite a lot, but I don't like Go's standard library templates. I wonder if it is possible to use https://github.com/valyala/quicktemplate with Hugo?
Zola [1] was created exactly for this reason. It even says so in the Readme. The templates are based on Jinja though, not mako. They also claim that their CLI is intuitive and documentation is good. I certainly found it more comprehensible than Hugo's.
When I made my site statically generated, I considered using Hugo, but I ruled it out after 15 or so minutes because i ran into the same issue with the docs. Ended up just writing a python script to do it which didn't take long
The only thing I did different is spent more than 15 minutes on trying to understand the documentation. Maybe it was just finding what the secret was that deserved such dense documentation.
I can sympathize with the author. I once attempted Hugo and gave up after a few hours and proceeded with vanilla PHP, which for most contexts is better and easier than any static site generator.
This goes to show that Hugo is quite excellent, but it's docs are lacking. Learning it was one long fight, but after having understood the basic concepts and gained experience using it for several projects, I really came to appreciate this static site generator.
Hey, author here. Thanks so much for the kind words! I love Hugo, and I wanted to give people a real-world tour of how to build something concrete with it.
I'm a big hugo fan. I contribute to their forum. I use hugo to build my site. I've used it on freelance projects. I could go on and on about it.
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:
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 wonder how useful this type of feedback is, and if the irritation over the docs could have been challenged into something more impactful.
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.
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".
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.
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.
I used Hugo for a while and remember their documentation and ultimately the implementation itself was confusing, which then resulted in an overly complex data structure that was hard to modify. Also tried a few other static site generators before just writing my own with python+markdown+jinja+etc.
The template engine is not so awesome (it is the Go template engine, really awkward!). Another thing that is really not awesome is that Hugo doesn't use semantic versioning, so that you don't have any idea whether the new version will break your project or not.
Once a Hugo update broke my website. So what I did was to take the latest version of the binary, and chugged it in the repo with the site code. Now I just never update.
Also helps with the urge to tweak things instead of writing (not that I write much anyways).
It is too big of an ask to ask a beginner to make a pull request, let alone contribute to Hugo Docs! I have raised close to three issues in the forum about the docs and how straightforward the issues I raised could be made but I was overruled by the mods.
And so does its themes. It seems that the good UI/UX web designers don't have interest to Hugo theme. I check the Hugo theme site [0], but difficult to find out the good one. Not like some React/Vue community.
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 :)
Writing good documentation is exactly like writing good software: you need to start with a known foundation (the readers prior knowledge/the OS platform) and then build layers of knowledge/software on top of that. One layer at a time. And never have circular dependencies. This is why I recommend only hiring software developers who communicate clearly. Software developers who can’t communicate clearly will write software that is badly structured and hard to maintain. A confused/unclear/unsystematic mind will write confusing/unclear/unsystematic documentation/software.
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.
> 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
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.
It's not ideal, but it is comprehensive. Infinitely superior to the Wordpress or Joomla documentation. It helps the system is less baroque to begin with.
I've made a lot of sites with Hugo, and so I appreciate the Hugo docs as a reference, but I agree that they're not suitable as a tutorial for new users.
I tried Hugo, and Jekyll and my biggest gripe with either is the Markdown format. I prefer RestructuredText and it is truly a superior format. I understand why Markdown is more popular but I can't understand why these static site generators support only Markdown. Sphinx supports both, and I use it everywhere. Paired with Pradyun's Furo theme, it truly is a far better experience.
I've been using Hugo for several years. But I'm mostly using freely available templates with minimal changes. Though some of those changes do require a lot of trial and error due to the lacking documentation.
Is the competition better? I see a lot of buzz around eleventy.
There's also Pelican, Jekyll, Gatsby and many others.
For this precise reason, I use Jekyll. I got so frustrated with Hugo, and when I went to Jekyll they had an entire "From start to finish, make a blog with Jekyll" in their docs.
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.
I gave up on the documentation and have been reading "Build Websites with Hugo" by Brain P Hogan.
It's a step by step guide to a build website, and I find Hugo more approachable and understandable than React Static and Gatsby.
Yeah, I wish there were a go version of the same minimal template engine/swiss army knife that is eleventy. Hugo is nice if you need some full fledged CMS workflow and can do everything the hugo way. But IMHO if you're just turning some markdown into HTML with a simple template then hugo has far too many concepts and abstractions. Eleventy is a breath of fresh air and can be learned and made productive in an afternoon.
To the author: I love that you use different formatting to break up your page, but I also recommend breaking up some of your paragraphs, as they are a little dense.
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 the significantly different 2.x version, but it's also a deliberate choice.
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
I had a bit of a battle to find out how to do a couple of things, but the weirdest challenge was to find out how to force it to refresh a Let's Encrypt certificate!
I absolutely love the performance, and now I have it working, I am super-pleased with the simplicity of the configuration for e.g. a nuxt static site with a PHP graphql server.
While I agree with a lot of the points made, I feel like it overstates the need to "read so many pages". You don't need need to follow each link as soon as its presented, and reading just the discussed page does feel like it gives me a usable starting point, despite that I have never used Hugo, and not read any other documentation pages at this point.
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.
It sounds like a basic thing, but it's also the main reason people write bad documentation
[1] https://documentation.divio.com/