Why Hugo’s documentation sucks - Sagar Behere

See Why Hugo’s documentation sucks - Sagar Behere on sagar.se

Hugo is awesome. Its documentation is not.

This is a common criticism of Hugo in that while it’s a fast and powerful static site generator, it’s documentation is hard to understand. Sagar gives the example of understanding page bundles, whose documentation isn’t self contained, meaning that you have to bounce around to get an idea.

The thing is, after having spent a lot of time tinkering with Hugo, I have now assimilated enough knowledge that the existing Hugo docs make perfect sense…most of the time. Maybe this is the case with other users of Hugo too.

However, I still remember how frustrating it felt while reading the docs for the first time…It felt like the official Hugo docs were the last place I should look at if I wanted to learn how to do something with Hugo.

For me, figuring out how to do something with Hugo was incredibly frustrating and much like Sagar, I’d look all over the web for an answer and even contemplate switching to a different static site generator entirely.

Fortunately, it looks like Hugo’s maintainers understand this and are looking into restructuring the documentation to follow the Diátaxis Framework which splits documentation into four parts:

• Tutorials for learning
• How-To Guides
• Explanations and
• References

Fixing these docs will need a lot of work. It might also need the services of a professional writer. Such an investment will need a lot of money so if you can, please sponsor the Hugo project.