Enhancement: Add tutorials, guides, and how-tos (based on the Diátaxis approach)

[christophberger]

Hi Hugo Doc Team,

I'm a Hugo user since 2016. The functionality is outstanding, and I cannot imagine using any other site generator.

However, I always found the documentation a weak part of Hugo. Whenever I try to find out how something works in Hugo, I end up digging through Hugo community posts and 3rd-party sites and posts.

Don't get me wrong. The documentation makes a great reference. What's missing is... everything else.

Take a look at Diátaxis.

Great documentation comes at four different modes:

• Tutorials
• How-To Guides
• Explanations
• References

Hugo's documentation is 100.0% reference.

A reference is not the kind of documentation that helps get familiar with a product or topic. References are for power users who already know how things work and need to look up a particular concept. What's needed is documentation for beginners, learners, and practitioners.

Adding tutorials has been requested in issue #2257, and adding guides was discussed in issue #389.

I would suggest bringing all these efforts together and working towards a Diátaxis-style documentation that reaches all the different audiences.

What do you think?

(P.S. This post may come across as kinda "direct", but that's how I am. I don't want to step on anybody's toes, but I am not the kind of guy who beats about the bush.)

[jmooring]

Good feedback. Duplicate of #1289, which started here:
https://discourse.gohugo.io/t/has-hugo-become-too-complex/29609/11?u=jmooring