Short of a complete overhaul of the docs site, one potential option would be to curate a “team-vetted” selection of How To guides / Tutorials / etc that already exist in the wild, and maybe link to them from a special section within the docs.
But, of course, the question is always “Who would commit to doing the work?”
I always keep Hugo up to date with the latest, and if there are any breaking changes, I just look them up or ask about them. I am notoriously stubborn and headstrong etc.
A little more about where I’m coming from: I’m Joe User. No ‘real’ coding experience (other than HTML and CSS) but willing to learn elementary stuff that helps me wrangle Hugo to a certain degree.
Perhaps for myself, being a software engineer makes it easy. I like Hugo. I enjoy using it. I like the structure. Somethings could be better, sure, but that’s anything.
Though, the question is, are static site generators for non developers? I mean we can make front-ends for them all day long like Netlify and etc. but at the end of the day, IMHO you can’t be a non coder and use static site engines effectively/efficiently, without mucking around in code of templates or Hugo upstream itself.
I’ve discovered almost all static site generators require you to be a developer, unless you’re just using other people’s themes and code, in which case, yes, you’re dependent on them to update any changes they need to make, and you can’t really complain about Hugo.
I’m sure there are many who will disagree with me.
And if we can have some clear guidelines about the formalism/structure needed for those sections to remains coherent, it would help us proposing some PR.
it even can lead at some step to some official frontmatter/partials we can use.
Hugo’s complexity is under the hood – hidden in a single binary.
If you use almost any other SSG you will probably end up in a dependency hell – one hell for each web project.
I switched to Hugo years ago because Ruby gem packages regularly were not compatible with each other as soon as one of them was updated. It always took a long time to figure out which package caused the error, and then to switch back to and stick to a specific version.
With Hugo everything just always works without any other installation.
I’ve only been using Hugo for less than a year. I’m in no way connected to IT professionally, I’m not a software developer by trade, and I got hit by the learning curve and the idiosyncrasies of the documentation more than once. Yet I think there are several things that need to be taken into account when discussing Hugo’s complexity and/or user-unfriendliness/steep learning curve:
Developing complex web sites is not easy. A lot of people make it their trade, and anyone can hire those professionals and pay money (sometimes good money) for a web site. Hugo is a tool that allows you to develop fairly complicated websites by yourself, but requires you to learn some things to do that sucessfully. Make some effort. If developing a web site was something that didn’t require any effort, those web developers would end up in other trades, you know.
99% of the time when I see someone complaining about Hugo being compicated and unfriendly the real story is that someone used a complex theme that either got abandoned or doesn’t suit the needs any longer. The theme’s author did most of the cognitive work for you; it takes much less effort to use a theme than to build a nice website from scratch. If you want to do more than the author intended with the theme, you need to learn more about how Hugo and themes work. Yeah, tough.
I ended up using a theme that the author abandoned, and I’ve had to fix it several times already to make it work with newer versions of Hugo. I made pull requests with the fixes, but the author never showed up to merge those. The stale repository is out there, the issues are documented, the fixes are documented as pull requests, yet every month someone opens an issue in the theme repository about the theme not working. They don’t even bother searching for the issue where the problem is described and the fixes are referenced…
Hugo is a static site generator. That means Hugo’s output is a bunch of static pages. Static pages can’t really be broken or abused (the server that serves them can, but that’s another story). There’s no security threat whatsoever in using an older version of Hugo. If it works for you, and you don’t want to spend the cognitive effort required of you to move to a newer version of Hugo, you can safely use an older one. Yes, you won’t get the latest and greatest features that way. Tough life.
Hugo is open source. Hugo’s documentation is open source. If you think it’s a little inadequate, you can help fix it. Not everyone is a programmer enough to fix Hugo, but you can help fix the documentation if you want. The little team behind Hugo welcomes every useful contribution and helps you to do it properly if this is your first time, don’t be afraid. If you feel like chipping in, please do!
If, despite all the things I’ve listed above, you still feel like Hugo failed your expectations and don’t want to deal with Hugo anymore, it’s sad, and I think I’m speaking for a big part of the community when I say we’re sorry to lose every member of the community and we’re sorry to see you go. However, as far as I know, you can get a full refund — yes, all the money you’ve paid for Hugo will be returned to you, every last cent! Isn’t that awesome?
The above observation is at the very heart of the issue raised in this topic.
That is why we direct people to the Requesting Help guidelines, that have been written by several contributors of this forum.
Also we did spend quite a bit of time extending the README of the Hugo Themes repository to offer detailed advice for theme submissions, but still we did see the same issues pop-up again and again because people never actually read the README.
For some reason many people have specific ideas about how certain things are supposed to work. Not everyone is willing to invest the time and get out of their way to learn a different tool that is not quite like the rest.
I agree with every word @jmooring said. Every jot and tittle.
Thanks, Joe, for the great links to Daniele Procida’s content. I’ve been pondering the same issues off and on for a while but hadn’t done any real research. Daniele’s presentation and the progressive disclosure approach captures everything that’s been rolling around in my head. Very helpful.
In my humble opinion, Hugo would benefit from two main new additions:
Plugin support and development
Integrated “lite” version.
Allow me to wonder you by exploring these two wonderful ideas.
Sit on a newspaper first, because by the time I finish this, I promise you: you
All right, here we go.
Plugins is what makes Wordpress big. Once you have a system and clear guidelines to develop plugins, developers can create and sell plugins cutting down 90% of the footwork for newcomers.
That takes me to the second point; the “lite” version. Hugo needs a version for the casual blogger. Someone who wants to publish a blog or small CV site should be able to do so without having to read one page of the documentation. As it is, to be able to do the simplest blog, you have to read at least half of the docs digging for the answer. Yes, we have the “Getting Started Guide” where you can be “up and running with Hugo in 2 minutes”, but people need to be able to customize their project. That doesn’t happens with Hugo, unless you want to spend the weekend reading the docs.
Plugins would take care of that issue.
Also, as it is, wordpress ===> Start small, customize to make something huge.
Hugo is the other way around. You start big and have to push your way around to get something small.
The blog post the OP linked explains it quite well. You can’t be up and running with Hugo in 2 minutes. There’s a half truth in that statement.
Hugo is destined to become something only more knowledgeable devs use, and that’s all right.
It will be fun to see newcomers have their way with it too.
Allow me to quote from here - the author is a fan of SSGs and Hugo
In one of my past Work Lives, I wrote user manuals for fax machines. (Obviously, this was a long time ago.) Our team prided ourselves on “writing for Grandma,” as we put it then, because our products were bought by people of all ages and experience levels. Thus, I am acutely aware how far short SSGs’ docs fall when it comes to being understandable by people outside the narrow circle of their own community, and sometimes even some within it.
At some point, the SSG folks will have to decide whether they do indeed want to maintain their role as Merlins rather than making SSGs accessible to ordinary users, particularly in corporate life. I mean, WordPress is a God-awful, performance-eating, security-defying thing—but at least your average Joe or Jane, and most notably your average Joe or Jane in corporate settings that aren’t going to hire dev help for them, can use it. Try that with any SSG.
Of course, you should also check the official Hugo documentation, but be forewarned that it’s clearly intended for a more technically oriented audience
FWIW, and with the greatest respect to those who have replied above, I find their comments mostly reflecting the issue at hand: coders/devs talking amongst themselves where jargon is a regular pattern of speech. It’s like I’m brosing Hacker News comments. The aforementioned ELI5 principle seems an almost foreign concept, something to be eschewed for reasons that escape me.
I’ll reiterate ad nauseam: my OP isn’t intended to bash Hugo or disrespect its devs and the general community. Far from it. I want Hugo to prosper and reach a wider audience. IMHO it’s necessary to reflect on an issue that hasn’t been addressed with some urgency during its rise to prominence: make Hugo better usable for Joe User. For the rest of us, so to speak.
Don’t we all? But we can’t expect @bep deal with that single-handedly, can we? Not with the number of the open issues in the repository…
That person you quote from claims to love Hugo, claims to see the big issue with its documentation, and claims to have impressive background in writing documentation, so obviously is capable of helping fix that issue, at least to some extent. It’s really great to have someone like that on board as an active member of the community, I’m sure he contributed a lot to the hugoDocs repository since he wrote that piece, let me just check… Oh, yeah, nevermind.
It isn’t. What is actually necessary is:
identify the issue (you already kind of did that),
find someone who knows how to fix it and cares enough about it to share the knowledge,
find someone who can do what needs to be done based on the abovementioned knowledge (not necessarily the same person as above) and cares enough to do it for the community.
You see, there are no SSG folks up there on Olympus Mountain doing their coder/devs things without caring much about Joe User. It’s just people who care enough to dedicate their spare time. Everybody is welcome to join. Every contribution matters.
Modules…this is precisely why some people find Hugo difficult.
Why not call the damn thing Plugins? Why “Modules”? Someone coming from WordPress sees the docs and–well, you know what? Crystal clear. Newcomers are not Hugo’s primary audience. Maybe they used to be, but not anymore.
That’s just an opinion, btw. So let’s roll with Modules.
I get it. Open Source. Thank you, really. Not complaining to @bep or anything. Great guy. The best.
Part of helping an open-source project is assisting the devs with the docs, yes. You are right. But, creating a welcoming environment for people to make suggestions and, God forbid, offer a few comments about where things are heading is also part of managing an open-source project.
If every person who tries to speak up needs to first show some badge of honor for having answered forum posts or updated the docs, this will go stall sooner than later.
P.S: I made a plugin for Hugo, by the way. Before the Modules update happened. Gave it away for free, Github and all. Not a single mention in the forums about the plugin (sorry, “module”). There is literally zero support for plugin devs. That also needs to change.
What page from the doc should I update before I can voice my opinion here again?
Because they don’t plug into Hugo. They’re building bricks that you can use to build your website, well, more like building sections, not individual bricks… Wait, there was a word for such pre-built sections of a building, what was that? Ah! “Modules”!
It may come as a surprise, but Hugo is not Wordpress. It’s not even a direct competitor to Wordpress. Yes, both can be used to build a personal (or not too personal) website, but that’s all they have in common. Different philosophies, different approaches, different means for different goals.
I totally understand the people that used to drive a pickup truck and get confused seeing no steering wheel, but as long as they finally accept the fact that they sit on a motorcycle having the trottle instead of the gas pedal actually does start making sense. And yes, this thing goes much faster and is much easier to handle in heavy traffic. No, you don’t get to haul your new furniture from Ikea on it, sorry; you could, but please don’t.
I am totally fascinated that so many people invest so much time, effort and knowledge – mostly in their free time.
I am not a programmer, but understanding Hugo is feasible. Hugo’s complexity is rather functionality . All in all I prefer generating a slim website with a super fast single binary SSG over dozens of MB of PHP scripts and plugins or tens of thousands of JS files. But it’s a matter of taste.
When I read some GitHub issues I sometimes don’t even understand what the guys are talking about. Programming is just not my profession. But this is not coder elitism – it’s just necessary technical vocabulary.
Hugo is a generous offer. If it is not the right instrument for you you don’t have to use it.
Coming from Wordpress and being not an developer I really appreciate that there are no plugins for Hugo.
Sure, you have thousands of plugins for Wordpress and you can find a couple for every use case. But, they come also with problems (code quality, maintenance, compatibility issue with each other, …) or caveats (premium). In the end, many of these plugins will probably remain black boxes for the average user and she/he has to trust the plugin authors.
With Hugo there are few out of the box solutions, but that has the advantage that I know what a module or shortcode does. I must no longer trust a black box.
Additionally, there are things where I find Hugo much easier then Wordpress. For example, I found creating and maintaining a multilingual site with Wordpress always very hard and frustrating.
I like the documentation. Sure it could be better with more explanations, examples and guides. But I use it mainly as reference book and in that respect the docs work very well for me.
I always found the community in this forum welcoming and friendly. Sometime the answers might be a bit harsh, but everybody has a bad day from time to time…
Hey. Author of the blog the OP mentioned in their post.
Firstly, Hugo is awesome and there’s no doubt about it. I’ve used Hugo for my personal website since 2 years and I really like how blazingly fast it is to render the pages and comes with no dependencies.
change, at least, please try to understand the philosophy of your product.
However, at this stage, all I care about is getting my blog up and writing new posts. I don’t wanna sound rude but as an end user, why should I care about the “philosophy” of a static site generator? I just wanna generate some HTML files. I won’t re-iterate my problems with doing them with Hugo but
Use a theme as is if you are total noob
Looks like you didn’t read and jumped the gun quickly. Happy to be a noob if making changes to a blog requires PhD in the art of static site generation.
P.S. I like Hugo very much for the things it offers. Not every tool offers everything for every user and similarly not every user has the bandwidth to contribute to the project. So, yes, while you can argue that Hugo is OSS and I should not feel entitled (which I am aware of, BTW), I also don’t have any obligations to be stuck with it. I posted my experience with it, maybe someone will find it useful, you may not.