Thoughts about Hugo's documentation

Meta
5

Thanks for the context! I reviewed the old documentation version, which indeed used a 3-column layout. The main issue was that the left and right columns didn’t scroll properly, which undermined the advantages of the 3-column layout. Otherwise, it offered good navigation and a Diátaxis-style logical order.

Since the old design already followed a 3-column layout with Diátaxis progression, my article adds limited new insight. So I deside to note my perspective, focusing on the Getting Started section for beginners with no prior website or SSG knowledge.

TL;DR:

  1. Getting Started feels brief and could include more practical, high-impact usage.
  2. Content irrelevant to basic usage might be excluded. Showing commands once per section could reduce confusion.
  3. Configuration basics like permalinks, Front Matter, Languages, menus, and segments could be included.
  4. A What’s Next section could guide users to the next step explicitly, complementing the 3-column layout. For example, users might want themes after Quick Start or understanding the Directory structure.
  5. Letting users skip full pages, not just middle sections, would improve usability, e.g., the deployment page.

Quick-start:

  1. I’m not entirely sure how to modify this documentation, but one thing that puzzled me before was why setting baseURL changed the hugo server output from ‘Web Server is available at //localhost:1313/’ to ‘http://localhost:1313/’. The documentation mentions this setting is for “your production site,” but it seemed to affect development output too.

  2. “Publish the site” (build the site) appears quite early. For users who might not even know markdown, let alone HTTP servers, using the hugo build command might not be immediately meaningful.

  3. I wonder if “Ask for help” and “Other resources” might work better at the end of the entire Getting Started section rather than in Quick-start? It feels like directing readers away from the documentation just as they’re getting started.

Basic usage:

  1. This page seems to provide relatively little actionable information for beginners. As the TL;DR suggests, newcomers could skip this page without much impact since the content isn’t needed for daily use or has been covered elsewhere.

  2. Beginners might not find the public directory contents particularly relevant since they’re still figuring out the project structure itself. For newcomers, build directory contents might not feel very “basic.”

Directory structure:

This was definitely my biggest hurdle as a newcomer. The documentation is quite detailed, but I think it might be a bit overwhelming:

  1. The directory tree codeblock under “Creates this directory structure” could perhaps include brief descriptions of directory purposes. I found myself wanting a quick visual reference rather than reading through detailed text lists, and text combined with visuals tends to be much easier to understand and remember instantly.

  2. The codeblock above, plus config/_default variants and the public directory, wastes 1.5 viewports, which might encourage fast scrolling.

  3. Concepts like Union file system feel quite advanced for this stage. Beginners now might be more interested in how to do basic configurations/modify themes through overrides rather than modifying the themes directory directly, but this approach isn’t really covered here.

  4. Beginners probably don’t need to worry about “hugo new theme” yet. This explanation might not be immediately relevant, since newcomers are usually focused on understanding markdown/Hugo project structure/git usage/frontmatter/configuration first. Internal architecture typically becomes relevant much later in the learning path.

  5. Theme skeleton has the same problem as Union file system.

  6. Beginners typically work with single themes, so multi-theme scenarios might not belong in “getting started.”

  7. It might be clearer to explicitly state something like “files in the project root will override theme files.”

  8. The structure of content directory seems really fundamental for Hugo but doesn’t get much coverage here. Should users use content/posts/article/index.md or content/posts/article.md?

  9. Should mention all relevant files, like explaining whether the resources directory and hugo_stats.json should be git-tracked, since this seems to be a common source of confusion, even among theme developers who sometimes don’t include resources in .gitignore.

Quick reference:

In the old documentation, this was part of getting started, so I’m including it here. The problem of quick reference is it’s not quick. The content of this section actually plays the same roll as reference in uv, which should be placed at the end of the document.

At least I wanted to log my beginner experience to hopefully avoid similar issues even after implementing Diátaxis.