3 ms·
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
by svat 4y ago
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.
- leetrout 4y agoI 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.
- projektfu 4y agoBeing 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 :)
- BossingAround 4y agoThat'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 :/.
- MengerSponge 4y agoHot 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.
- twodave 4y agoI'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.
- speed_spread 4y agoEven 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.
- WesternWind 4y agoThis 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.
- twodave 4y agoAnd 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
- manachar 4y agoThat'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.