I’d be super happy to contribute to the writing, editing and rewriting of docs. I’m new to Hugo, but I love documentation.
In my experience so far (reasonably valid as a new user), the documentation appears to be grouped for internal developers, or seasoned users. So, if I want to learn all about Taxonomies, I can. But there’s no easy way to understand how Taxonomies fit into the overall development experience. I feel almost immediately lost as there’s no 10,000ft view of the project.
I think the AngularJS docs could serve as an excellent reference point. They do a great job of separating the introductory / conceptual stuff from the technical breakdown. The best page by far is Developer Guide > Conceptual Overview. It dedicates a few lines to each component and offers links to the API reference.
Regarding the current Hugo docs, this is my experience thus far:
About Hugo
- There’s nothing here actually about Hugo. It’s the release notes, roadmap and licence. That was my first huh? moment and it happened immediately.
Getting Started
-
Introduction - A complex mix of things: What is a Static Site Generator? How Fast is Hugo? A little about the Concepts (with no intro to the terminology). Feature List. History of Hugo.
-
Quickstart - good, no need to talk so much about installation - just the link. Otherwise good.
-
Installing Hugo - fine, but should be first. Certainly not after Quickstart.
-
Using Hugo - should be renamed to Command Line Usage. Remove the deployment stuff into another page (but crosslink it here).
-
Configuring - good, rename to Config Files.
Content, Themes, Templates, Taxonomies and Extras
I’ve not read through all of these yet, but this is probably the most troublesome part. My gut feeling is that I’ll need to flip-flip between the intros for each section in order to understand how they all fit together. I’m not looking forward to the experience, but am excited to reach the aha moment at the end.
What I think is lacking / missing
- A page about nomenclature. The intro pages, quickstart etc. use Hugo terms straight away, and it’s confusing. Organization… do you mean a group of people, or how I keep my files in order? Or organise my Posts? What’s a Section? A Section could be anything, it’s like “thingy”. And in HTML terms a
<section>
is well defined. Taxonomies? A grouping of Sections I assume? Or maybe a group of Content… Wait up, are Taxonomies and Organisation the same thing? And so it goes on.
I hate to hark about the AngularJS Docs, but this table is fabulous to see early on (below) - the descriptions are amazingly naive but seeing it all together really helps paint a picture of the whole system. The order appears to reflect the order that a new user would learn AngularJS. Yes, I absolutely need to know about Data Binding, but not until I’ve seen it used in Templates , Models and Scope… you get the picture.
-
There’s a lot of missing indexes. I really want to see a list of pages and a line about what they contain. As it stands I have to pick (almost at random) and hope it gives me something I want. The Extras section is a great example - I see “Scratch” but until I skim the page I have no idea what it is.
-
Crosslinking. Lots of opportunities to read more. on each page, that are sadly missing. Take a look at the Quickstart page for a good example, if I want to read more about templates I have to hope to find the right page via search or the menu - which has an uncomfortable air of luck.
I’ve always like the way Amazon says “people who viewed this item went on to buy…” - is there an opportunity to do something similar with each page? So after reading “Installing Hugo” I probably want to be prompted on to quickstart rather than to the the contribution guide (which should be a page in it’s own right).
- Those Previous / Next buttons - they’re pretty, but useless due to the unusual grouping of content and the lack of titles. See Mystery Meat Navigation.
Overall Verdict
Seemingly awesome software, documentation is good, but difficult to navigate. Particularly tough to get an overview.
In a strangely ironic turn, I think I need to learn more about Hugo before I can properly contribute to the documenation - I made one simple Pull Request for the docs but the difficulties I’m having in using Hugo have stopped me from doing more.