Hacker News Reader

Comment by _benj | Hacker News Reader

Thanks for this! One of my frustration with tools nowadays is that they aim to be so "user friendly" that actually make things complicated and thus understanding how something works, which allows one to be more productive with a tool, is hidden under tons of layers of complexity and simplistic "getting started" that can indeed make an amazing looking website with 1 command, but from there on, trying to figure out _how_ that amazing website works and how can I adapt it for my need is a rough journey!

View on HN

Exactly. I ran into this when trying to set up Hugo, and wrote for myself a notes page with the following:

# What is Hugo?

`hugo` is a program that takes some .md files (ideally, conforming to a certain directory structure) and creates some .html and .xml files (conforming to another directory structure).

This is the minimal command:

    # Create input directory structure to silence warnings
    mkdir content layouts{,/tags,/categories}
    touch layouts/home.html layouts/{categories,tags}/list.html
    # Run hugo: creates public/ and resources/
    hugo

…and building from there.

If you read the Hugo documentation, it talks about all kinds of stuff but doesn't explain anything from the bottom up: apparently the usual way is to start with a pre-existing theme or site as template and edit it, but that's not explained anywhere either. After you eventually learn exactly what Hugo is, it becomes ok to use.

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

There's very few documentation experts out there. Those who write the docs are either devs who write broken English, or English majors who don't understand a lot of the tech stack. In either case, they usually miss the target persona, and what are the reader's needs.

Writing docs is hard :/.

I'm not a hugo expert, but the two main things that I needed were:

1. An understanding of what variables are available, and where. Hugo nicely collects a lot of useful info but it is difficult to know what it all is and where it is. https://gohugo.io/variables/page/ is a good start but it is difficult to know how these are populated.

2. Hugo is implemented in Go, so under the hood everything is strongly typed. But the Hugo documentation throws that all away and presents the dynamically-typed interface that Go's html templates provides. The problem is, figuring out what anything can do is made very difficult by that. So, ok, I have a .Content or a .Data for this page... but what is that? Is it a string? Is it an object? If so, what can I do with it? I have to experiment to find out, or grep over a couple of templates to figure it out.

Honestly if I had to make just one suggestion to the Hugo docs team, it would be, strongly type your entire documentation suite. Tell me what the type of everything is, and the resulting methods/functions I can use it with. (If it's an interface, fine, I don't mean all the maximally static types necessarily.) That wouldn't fix everything, but it would fix the frustration I experience of visiting https://gohugo.io/variables/page/ and still wondering what any of that stuff actually is.

Hot take: The docs are an important part of the product. If you notice that the docs are bad, the product is bad.

Docs are hard and thankless, but ¯\_(ツ)_/¯ them's the breaks.

Even hotter take, you can have a well documented shit product and it'll be better in a lot of cases than a quality product with no docs.

That's pretty much the space Wordpress thrives in, isn't it?

How shit the product is for Wordpress is a matter of debate, but the documentation and ecosystem around it is robust enough to make it fairly easy to hack and use/abuse to do what you want it to.

This is true. Docs, re not necessarily considered important features of the product itself but they make a huge difference.

Other things that I pay attention to are built-in integrations with other tools, the ability to import and export data, familiarity to users, similarity to existing tools, tutorials that leave users confident, and documentation with examples of use cases are all similar factors.

And if your project is open source and the docs are clear and show good vision, you might even attract folks to come fix your broke-ass code :D

I'd even take this hot take up a few more degrees and say the docs quality not only represents the product quality, but also validates it. In other words, you can't know whether your product has a chance of being good unless you're _able_ to write good docs for it.

> ...If you notice that the docs are bad, the product is bad...

This right here is so correct! Given the option of 2 (or more) products/services, in my mind, the one with the best documentaiton wins...because it usually means it is the option that is more easy to implement...or at least i can research how to make it the esier option to implement, etc. Good docs for the win!

I've been blessed to have started my career at a place where the docs were surprisingly comprehensive, and I've done my best to carry that torch. My old DevOps team wouldn't have it any other way.

I got a thumbs up just a few days ago on a Confluence doc I wrote months ago explaining at a very high level what two legacy parts of our software does, from a new hire I have never met or spoken to. That really made my day.

I plan to record a small (4?) series of videos about starting with Hugo from scratch. Would love to hear any pain points you specifically think need to be addressed.

Being a video is a pain point for me. I much prefer a useful text tutorial with code I can copy, etc. But I don't want to be a choosy beggar so you do you :)

PicoCMS is the real friendly CMS for serving static files.

1. Upload PicoCMS to the least expensive LAMP shared hosting, by FTP.

2. Upload markdown files to /content.

Viola.

You may also want to download themes or make your own with Twig templating system.

IMO if you're a software developer and you can't figure it out in 10 minutes, it isn't really that friendly.

Hmm, that sounds good but when I go to the homepage it gives me buttons for learn more and download, neither of which work and the focus is all messed up. I know it's probably not the CMS part that's broken but if the website for a website builder doesn't work it doesn't inspire confidence.

? I just checked and it works fine for me

Seems fine on a desktop, but doesn't work on android chrome for me.

Yes, I also found it difficult to understand how Hugo worked internally.

If you’re ok with NPM, Metalsmith is a trivially simple static site generator, where you just write JavaScript code to customize it (and of course you can plug in templating tools). If you don’t like NPM, but like JS/TS, I started a port/rewrite of Metalsmith for Deno, I can share if anyone’s interested.

Metalsmith is cool! I hadn't heard of it til now but it looks sweet.

I actually made something similar except mine isn't designed for static sites specifically. It just takes markdown, parses it into HTML (with code highlighting of course) and stores the html and frontmatter in an in memory sqlite database that gets rebuilt each time you save. Not the most efficient choice, but it makes plugging it into any front end framework like nuxt or next or svelte really easy, particularly if they have server side rendering. I guess it's almost halfway between this and PicoCMS. And you get full text search.

It's md2blog for anyone who is interested <https://jaredkrinke.github.io/md2blog/>

The Show HN discussion from 2021: <https://news.ycombinator.com/item?id=29382091>

Specifically, the internal Metalsmith-like core is here:

https://deno.land/x/goldsmith@1.2.1

Although I now see that I only documented in-code. It’s very similar to Metalsmith, except based on Deno, in TypeScript, async, and standarized on RegExp instead of a grab bag of globbing libraries.

Edit: generated docs link:

https://deno.land/x/goldsmith@1.2.1/mod.ts

Unless a tool is so ubiquitous and widely used that it becomes a new standard (like JavaScript), over abstraction is a very real problem.

Reply on news.ycombinator.com