[HN Gopher] Hugo is awesome, its documentation is not
___________________________________________________________________
Hugo is awesome, its documentation is not
Author : KlatchianMist
Score : 219 points
Date : 2022-03-02 14:47 UTC (8 hours ago)
(HTM) web link (sagar.se)
(TXT) w3m dump (sagar.se)
| ivanech wrote:
| 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
| bigpeopleareold wrote:
| 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.
| fmajid wrote:
| 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.
| vanisher93 wrote:
| I mean, I get it, but why not opening a couple of PRs then? It is
| an open source project after all.
| kvnnews wrote:
| 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.
| synergy20 wrote:
| I now think rust-based mdbook is simpler and better than hugo,
| give it a spin. the limit of mdbook is that it's one book only.
|
| 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.
| austinpena wrote:
| I really dislike that I had to, but I migrated to Next JS for the
| sole sake of the IDE support that comes with JSX.
|
| 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.
| cryptos wrote:
| 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.
| yoz-y wrote:
| 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).
| vehemenz wrote:
| 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.
| sandreas wrote:
| I pretty much had the same experience. If someone is interested
| in my personal notes how to get started from scratch with hugo,
| see
|
| https://pilabor.com/blog/2021/05/building-a-blog-with-hugo/
| throwaway284534 wrote:
| 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.
| regus wrote:
| 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.
| rr808 wrote:
| I've had the same issue with Helm Templates - "they're just Go
| templates".
| SomeCallMeTim wrote:
| Very much the same experience.
|
| 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.
| PaulHoule wrote:
| 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...
| dmitriid wrote:
| > 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.
| rr808 wrote:
| Right its easier to switch entirely to something else. If you
| use Micronaut, Microprofile, Vert.x etc your life is much
| easier.
| PaulHoule wrote:
| 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.
| rr808 wrote:
| > It's very nice that Spring provides a "general
| configuration file" that lets you patch together a few
| objects without having to compile anything.
|
| Used to with xml files, now its attribute driven, just
| another way to double the complexity again :)
| dmitriid wrote:
| Micronaut is slowly but surely going in the same direction:
| dozens if not hundreds separate guides with basic examples.
| PaulHoule wrote:
| 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.
| oauea wrote:
| > 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.
| PaulHoule wrote:
| 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).
| andrelaszlo wrote:
| 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.
| Nagyman wrote:
| Django has some of my favourite docs, organized incredibly
| well:
|
| * Tutorials * Topic guides * Reference guides * How-to guides
|
| https://docs.djangoproject.com/en/4.0/#how-the-
| documentation...
| Starlevel001 wrote:
| Sphinx-based docs are usually excellent due to how easily
| it lets you flow between tutorials and references.
| PaulHoule wrote:
| 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.
| teach wrote:
| There are, in fact, four types of documentation[0]:
|
| 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.
| shadowgovt wrote:
| 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.
| andrelaszlo wrote:
| Yep, had this problem several times already.
|
| 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 :)
| PaulHoule wrote:
| 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.
| earthboundkid wrote:
| 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.
| jdubb wrote:
| 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?
| evanelias wrote:
| 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!
| chipotle_coyote wrote:
| 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).
| lolinder wrote:
| 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.
| 0xbadcafebee wrote:
| 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.
| jordanmorgan10 wrote:
| 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.
| quyleanh wrote:
| 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
| :)
|
| [0] https://themes.gohugo.io/
|
| [1] https://imblien.com/
|
| [2]https://github.com/victoriadrake/hugo-theme-sam
| awill wrote:
| 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.
| byteski wrote:
| well I figured out how Hugo works only by "clone the existing
| Hugo theme, change something, see what happens".
| atishay811 wrote:
| 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.
| svnpenn wrote:
| > 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".
| wink wrote:
| It's been a while, but I'd sum it up as:
|
| 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.
| dkarl wrote:
| 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.
| karaterobot wrote:
| 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.
| bojanvidanovic wrote:
| 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.
| nouveaux wrote:
| > 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.
| [deleted]
| recursive wrote:
| Hugo documentation is a monad tutorial.
| andrelaszlo wrote:
| 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.
| digianarchist wrote:
| 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.
| azangru wrote:
| As a web developer, primarily on the front end, all I can say
| these days is: Eleventy.
| qbasic_forever wrote:
| 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.
| CA0DA wrote:
| 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!
| ljm wrote:
| 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.
| systemvoltage wrote:
| 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.
| autarch wrote:
| 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.
| corobo wrote:
| It's a shame we can't peek into alternate universes to
| prove/disprove but I have to imagine those titles
| wouldn't have nearly as many upvotes
| autarch wrote:
| You're probably right, but I think not being a jerk
| should trump HN upvotes.
| systemvoltage wrote:
| 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.
| autarch wrote:
| 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.
| systemvoltage wrote:
| The only thing I agree here is that better language
| wouldn't hurt. I don't think most people get "triggered".
| That's a vocal minority perpetuating a culture demanding
| a sort of conformity against _their_ definition of
| "micro-aggressions" and "triggers" with no regards to a
| larger consultation with the society.
| autarch wrote:
| I didn't use the words "triggered" or "micro-
| aggressions", so what exactly are you quoting?
|
| Saying "your project sucks" or "your project docs suck"
| is not a _micro_-aggression, it's a macro-aggression, or
| as I prefer, being a jerk. I think most people would
| react negatively to that sort of statement.
| dahdum wrote:
| 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.
|
| It's typical open source toxicity.
| chipotle_coyote wrote:
| 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.
| [deleted]
| [deleted]
| adriangrigore wrote:
| Feedback on my static site generator's documentation if we're
| here? :D https://mkws.sh/docs.html
| svnpenn wrote:
| > 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?
| adriangrigore wrote:
| Not sure if people who understand
|
| > 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
| svnpenn wrote:
| Where are the previous versions?
| adriangrigore wrote:
| They're not listed, good idea to list them somewhere.
| alleycat5000 wrote:
| I've also found Hugo's docs hard to use, but had a great
| experience learning it from
|
| https://pragprog.com/titles/bhhugo/build-websites-with-hugo/
| rsolva wrote:
| 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.
| hugopipes wrote:
| I
| say_it_as_it_is wrote:
| Rather than contribute to improving the documentation, why not
| spend hours creating a web site and blog post flaming about the
| problem instead?
| eloff wrote:
| 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?
| sreevisakh wrote:
| 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.
|
| [1] https://www.getzola.org/
| eloff wrote:
| Nice, thanks for the link, it looks interesting. Implemented
| in Rust.
| rimutaka wrote:
| I switched from Hugo to Zola. Happy as Larry.
| StevenWaterman wrote:
| 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://documentation.divio.com/
| [deleted]
| aae42 wrote:
| > 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
| _jal wrote:
| 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.
| remoquete wrote:
| This. No matter what fancy docs framework or system you use,
| you need people dedicated to the craft.
| mholt wrote:
| 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.)
|
| [1]: https://caddyserver.com/docs/
|
| [2]: https://caddy.community/c/wiki/13
| rsolva wrote:
| 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...
| earthboundkid wrote:
| I tried to start a discussion about documentation as
| reference vs. tutorials on the forums too:
| https://discourse.gohugo.io/t/discussion-of-hugo-theme-
| from-...
|
| I think the problem is just that no one wants to bell the
| cat. :-(
| abnercoimbre wrote:
| > no one wants to bell the cat. :-(
|
| Never heard this refrain before! What does it mean? No one
| wants to get on leadership's bad side?
| lolinder wrote:
| https://en.wikipedia.org/wiki/Belling_the_Cat
|
| > 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.
| fastaguy88 wrote:
| 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.
| chatmasta wrote:
| Love this system.
|
| BTW, I think this might be the updated version of the same site
| (decoupled from Divio): https://diataxis.fr/
| rsolva wrote:
| Thank you for the link, this system really deserves its own
| dedicated website :)
| shadowgovt wrote:
| I've found one of the recommended books very useful for getting
| started (https://www.manning.com/books/hugo-in-action).
|
| But, (a) it's preprint and has copy-editing bugs and (b) it
| doesn't address the issue of the lack of reference docs.
| hugopipes wrote:
| 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.
| thrower123 wrote:
| There's never been a CMS system that doesn't suck in this exact
| way. It's the nature of the beast.
| throwawayboise wrote:
| Yes, it gets back to essential complexity vs. accidental
| complexity, like most software that does anything non-trivial.
| jerf wrote:
| 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.
| throwaway5486nv wrote:
| How could some framework be awesome without having good
| documentation?
| rsolva wrote:
| 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.
| chrisbrandow wrote:
| As someone who is a competent iOS developer but not much of a web
| developer, all I can say is that I _completely identify_ with
| this critique.
|
| The Hugo docs are just straight to the deep end.
| subpixel wrote:
| 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.
| zellyn wrote:
| 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.
|
| [1] eg: https://zellyn.com/2022/02/cs-ramble/1c/
| Kon-Peki wrote:
| 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.
| dahdum wrote:
| There are so many ways to title the article and approach this
| topic, yet the author still chose a petulant and insulting one to
| vie for attention.
| unfocussed_mike wrote:
| 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.
| corobo wrote:
| 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
| unfocussed_mike wrote:
| 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.
|
| But it really was a bit mindbending.
| amai wrote:
| Hugo would be a lot more awesome, if they would fix this 7 year
| old issue :
|
| Add ability to generate per-{year, month, day} archives:
| https://github.com/gohugoio/hugo/issues/448
| WaitWaitWha wrote:
| I believe we also discussed Hugo here:
| https://news.ycombinator.com/item?id=30142558
| detaro wrote:
| 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.
| hombre_fatal wrote:
| I know what they are talking about.
|
| 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.
___________________________________________________________________
(page generated 2022-03-02 23:02 UTC)