這是我曾經在 Hugo 論壇提起的建議，當時想寫這篇文章的原因是看到文檔正在重構，也正好那段時間自己正在研究撰寫文檔撰寫的知識，因此想說給一點意見，免得重寫之後還是一樣的問題。

先整理一下時間線：

1. 2025-05 我在部落格撰文檢討自己不夠成熟
2. 2025-09 寫了建議原文，當時我已經看了幾個月的文檔、回了幾個月的用戶問題，又加上自己在研究文檔撰寫，因此提出建議，原因如開頭所述
3. 2025-10 收到回覆，只能隱約發現他不想解決問題，因此不指名道姓的寫了三明治說話法和放下工程師心理，這兩篇文章完全沒有提到 Hugo
4. 2026-01 蘇格拉底事件發生，發現他的回覆不對勁，因此把所有內容攤在陽光下，所以本文的建立時間是 2026-01，而建議內容如第二點說的寫在 2025-09

這篇和蘇格拉底一樣設定 noindex 以避免不必要的搜尋引擎曝光，能看到這篇文章也表示你不是從搜尋引擎進來的。

Hi Hugo maintainers,

I’m a theme contributor who sometimes fixes bugs. I’m excited to hear that the documentation is being restructured using the Diátaxis framework.

First, thanks for your ongoing maintenance and responses to the community. Providing example repositories when people ask questions takes a lot of effort and is really helpful.

I’d like to share some thoughts about the documentation. If anything comes across as critical, that’s not my intention, I just want to help Hugo’s community and users.

I’m not sure if this is the right place to share this, and many of these issues have probably been considered already or may be difficult to implement. But as a user, I thought I might offer a different perspective from the developers.

I’ve looked through these documentation sites extensively, and much of my feedback comes from them:

• Docusaurus
• Vitepress
• uv

Current Issues I’ve Noticed

As a reader, the main problems I encounter are:

1. Hard to locate specific content, I use search 90% of the time instead of navigating through menus, while with other docs I rarely need search
2. Unclear reading progression, it’s hard to know where I am or what to read next

Documentation Ordering

This feels like the most important issue to address. The current alphabetical sorting makes the docs harder to navigate, and the behavior is inconsistent. Most sections use alphabetical order, but important content like the new template system gets moved to the front.

This should be fixed with the Diátaxis restructure though.

Card Layout

The card layout creates navigation issues for me. I often lose track of where I am in the documentation and what to read next. Cards have both horizontal and vertical relationships, while other documentation sites only have vertical relationships between sections, creating a clear reading flow.

When I try to find information visually instead of using search, I have to read through all the title names everytime to find what I need (even for documents I just read), or mentally go through the alphabet for alphabetically sorted sections (this doesn’t apply to functions and methods, which are naturally suited for alphabetical ordering).

Three-Column Layout

The three documentation examples I mentioned all use a three-column layout: left sidebar for document structure, main content in the center, and right sidebar with page TOC.

I used to wonder why so many docs use this layout. It seemed boring that every site looks the same. But after thinking about it, I realized everyone uses it because it is the most effective for reading. The main benefit is:

You always know where you are in the documentation and what comes before/after.

This lets authors clearly guide users on “how to read the documentation.” The current card layout with inconsistent sorting makes it hard to understand progress and what to read next. I think many people end up jumping around the docs, which means they’ll inevitably miss things.

The three-column layout also addresses another UX issue: Hugo’s current documentation lacks clear visual separation between “In this section” and “On this page” navigation. Users must scroll down to access the page TOC, but since they typically arrive at a page from the section level, they’re immediately presented with the same section information they just navigated from. This also forces users to scroll back up after reading to navigate to the next section.

Top Navigation Bar

The top nav bar would be a perfect match for implementing Diátaxis. Looking at VitePress/Docusaurus docs, the synergy is clear:

1. Basic usage goes in docs/guides (whatever the name)
2. Advanced usage goes in API. Regular users never need to click into API unless they’re customizing themes

This reduces complexity by about 70% for regular users. Most people probably never need to read functions/methods section, and this design lets users know “I never need to click into the API section because I’m not customizing or writing themes.”

Diátaxis Ordering

uv has the clearest documentation structure I’ve seen, which is why I’m referencing it:

1. Getting Started lets you get something working quickly
2. Guides cover daily usage with shorter articles
3. Concepts are more detailed with longer articles. Also, I notice that when I see the “Package indexes” section I naturally don’t want to read it, and everything after that is indeed non-essential
4. Reference section listing all usage (corresponding to the top nav position for API mentioned earlier)
5. All sections flow logically from top to the bottom, creating a clear learning path that our docs currently lack

Though uv is a different type of tool from Hugo, I think we can still learn from their approach, especially regarding Diátaxis implementation.

Usage Guidance

Following Diátaxis principles, I think more effort should go into describing theme usage, since most people are users rather than developers. For example, as someone who sometimes answers questions for theme users, there are many people directly modifying theme folder contents instead of overriding them (when I think this is actually one of Hugo’s major features that other SSGs can’t match), and some users even get confused between _index.md and index.md. These basic topics are surprisingly hard to locate in the current documentation structure.

Misc

Section naming: from my perspective, these two names seem similar:

1. functions
2. methods

I don’t really think about the difference between them. In my mind they’re both “things I use in layouts”—but they’re separate sections. Maybe the distinction is necessary, but they should at least be listed together.

Javascript: the current documentation pages have transition effects that cause issues. When I’m quickly jumping between pages, I often need to click the same link multiple times before it actually navigates.

Summary

I believe that separating documentation for general users and developers, and intentionally guiding users through a logical reading sequence, would significantly improve the overall experience. I’m really looking forward to the transition to the Diátaxis framework and am confident these changes will make Hugo’s documentation even more effective. Thanks again for all your ongoing maintenance work!

然而我得到了這樣的回應：

My 2 cents…

1) There is work underway to restructure the documentation. See #2996. This is not a trivial task. I’ve already spent > 100 uncompensated hours on this, and it’s roughly 30% complete.

2) As part of the above there’s a tutorials section that can be augmented over time, but it will never satisy everyone due to individual learning styles.

3) Topics such as this are, to an extent, demotivating.

不採納建議我完全 OK，如果他不想討論，有自己的計畫，覺得我的建議很爛，或是其他一百種不喜歡我的文章的理由，我完全可以接受，建議本來就是建議，沒有一定要採納，不喜歡就不要用，回收到、我會參考、我們考慮過了、我認為不可行、甚至隨便一種冷處理都好，結果回的比冷處理更糟糕。我在講具體建議、使用癥結、被多方採納的編排方式、我分析這些編排方式背後的優點、經過時間驗證的 UI 設計、有實際案例的用戶困擾，結果他回了三點沒有任何一點在講文檔本身，不回應任何具體的文檔結構、編排方式或使用者行為分析，他在講的是：

1. 強調已投入的大量無償時間（焦點從文檔設計轉移到維護者的付出）
2. 指出任何教學設計都不可能滿足所有人（我的文章絕大多數在講 UI 編排，根本沒說到教學「實際」該怎麼寫）
3. 以「這類討論令人感到氣餒」作為收尾（回到自身感受，避而不談文檔本身）

最糟糕的是我當時又道歉了，怎麼每次重新思考到跟他的對話就是我根本不該跟他道歉阿。

（原本寫了一段這實際上符合心理學的什麼什麼但是我怕被告...只好刪掉改成客觀事實）。