There is a discussion happening now over at HN that underlines the need for reorganizing Hugos documentation, preferably using the principles outlined here.
This discussion has been had here at the forum earlier, and I have brought up my own experience coming to Hugo as a beginner and trying to use the docs as I learn.
Please join the discussion here and/or at HN. I believe we can improve the developer experience for Hugo by having this conversation together!
It is possible that most Hugo users are far more knowledgeable, or patient, than I am and therefore have not faced any of the issues described below.
There surely is a term for something where someone with knowledge in “something” comes to “something else” and tries to use their experience in “something” to explain “something else”.
One thing I am always repeating over and over again is: Semver posits that a version 0.something is an unfinished product. As soon as Hugo reaches version 1 I will spend time reading through things like this 
Until then I use words to ask questions here on discourse or use a system that is more mature.
As long as nobody with wades of cash is supporting Hugo (it’s developers and project managers and community managers) it will stay inferior to cash-backed projects.
Knowing what can be improved is nice, having the resources to actually improve that is a luxury.
But it’s always nice when “the big guys” talk about something I am invested in.
This is a crucial point, of course! But I also think the community contains enough developers using Hugo, both personally and professionally, to band together and start assembling new documentation based on the Diátaxis Documentation Framework. I would love to help out where I can.
Can I ask what happened to your prediction that Hugo “will receive a perfectly structured and searchable documentation site” in 2021?
If you or other people are still working on this, then it’s best we as community remain patient, rather than intervene with ongoing work and suggest a change of documentation framework.
Nothing will be worse than people wanting the docs to be written with framework B when most of the work is already done with framework A.
We’re not in a hurry and appreciate everything the maintainers, developers, and writers do. 
That prediction was hope. There was an attempt to restructure the documentation that somehow fell asleep. For instance here.
What maybe is needed is people NOT being developers of the program itself joining the efforts to write a documentation. The developers know in their dreams what Hugo does how. It needs to be put into a structure that normal people understand.
I agree with @bep’s thinking back in November 2020:
Whatever we do, I suggest that we start with totally blank sheets, and a way to do that would be to just move all the old stuff one level down (or something). Then we could do something ala: “This section currently is on the short side; you may find more useful info in the old docs …”
I think we also need to start fresh with a new theme as well …
See also Architectural Overview of Hugo: Components, Connections and Interfaces
Gatsby seems to live by the Diátaxis method.
This is an important point. I have recommended Hugo to friend who are semi-techy, and they have all given feedback that underlines the challanges for a newcomer to get started. To gather and sum up this feedback could be very helpful to have when thinking about new docs.
That said, using the Diataxis Framework as a guideline would already address many of the problems facing newcomers.
The Hugo documentation is really hard to understand for begginers. The name of the feature used are not easy to find see example here.
Access to knowledge in Hugo is limited or restricted my opinion as I mentioned here
Also there are things you cannot find the answer to in documentation like this one Select params.title 2 words separately - #5 by pitifi9191
after 3 months of trying and after getting my account blocked, I quit on the documentation improvement. So good luck and thanks for discussing this as it is really needed.
Whats your Github account? I would like to re-trace your journey to improve the docs here.
I am currently working on an article (for someone else, not my own site) about sections in Hugo, and the process that this fellow described sounded eerily like what I’ve been through while researching the subject in the documentation. 
Just sayin’.
I think it’s a fair criticism, but I’m not sure how it could get fixed without paying someone for a rewrite.
Not sure we need another thread on this:
Moved this post to the original topic.
Sorry I looked but didn’t see this thread somehow.
Reading through now, I think there’s general agreement that this is a real issue, that changing to a tutorial vs. reference framing would help, and that someone else should do all the work. 
Hey, I’m currently learning Hugo and would like to share my experience so far with you.
First of all, I would like to say that Hugo is exactly what I always wanted but didn’t know I wanted. Hugo gives me the opportunity to make my website as flexible as possible without taking away my decision-making authority over the concrete design or structuring. I thoroughly believe that in the right hands, Hugo is an extremely powerful tool for building the most complex of websites.
As a beginner, however, I find it very difficult to get to grips with Hugo. These YouTube tutorials are very helpful to get a first impression of Hugo, but they are not enough to replace the documentation. And the documentation is, to put it mildly, not ideal for finding your way around for the first time. For example, I recently wanted to configure the taxonomy pages, but was simply unable to work out how to do it properly. I am not a native speaker, but I understand English quite well, and yet after hours of googling, I had to sit down in peace with a cup of cocoa and read aloud the article on taxonomy in the documentation to gain a rudimentary understanding of it.
I finally realised that all the information I needed was actually there, but it is, I am sorry to say, poorly compiled. As a beginner, I would like to read an article that explains step by step what exactly I have to do. However, I get the impression that the documentation is written from the developer’s point of view and from how Hugo works behind the scenes.
In the documentation, the lookup order is presented in a table. However, as a beginner, I would first like to have the answer to the question: “What file do I have to save in which folder under which name to get what result?” I can always look up the details of the concrete implementation afterwards.
Thanks!
it seems like the Hugo docs are structured as a reference but presented as an explanation/tutorial.
I will shamelessly plug my unanswered topic here. I have really wanted to try page bundles, but I really can’t find any information on the questions I asked. So, I stuck with the safe route of having images in the static folder. I have encountered other issues here and there like the example @pitifi9191 shared above, and it makes me miss how easy Jekyll’s documentation was easy to use. Coupled with the evolving nature of Hugo which allows breaking changes meaning some tutorials you read online could be outdated in six months!
I’m not a programmer, but it was a blast starting to work on hugo. Their concepts are so powerfull.
Sure i had to use the forum a lot, reference documentation was not enough.
And you have to think the hugo way. Took me some times to get the full picture (basically vocabulary was a problem for my french speaking)
But i so often see questions obviously from someone who wants a tool adapted to their way of doing web sites. And not trying to adapt them to the hugo way of thinking
I saw that a lot with people coming from php and not willing to understand the object way of thinking (dot, context). And asking staight away before really trying to make things work.
Yes it has to evolve toward great guides/diataxis.
But hugo is a beta software, evolving a lot (amazing today compared to 3 years ago), and no paid dev.
Come back for 1.0, after all those people sponsored the project.
Unleash the trolls.
[EDIT] just found the perfect example on HN about those. They need a tool to fullfill their way of thinking. Do not want to learn or evolve. So yeah go php, go
I can sympathize with the author. I once attempted Hugo and gave up after a few hours and proceeded with vanilla PHP, which for most contexts is better and easier than any static site generator.
or the next level genius
I have not used Hugo and I have no idea how powerful it is but I am quite skeptical. It’s hard for me to believe that it is more powerful and flexible than Django and Django’s documentation is very good.
or the full of certitude guy who missed a bit the v0.x.y thingy
Another thing that is really not awesome is that Hugo doesn’t use semantic versioning, so that you don’t have any idea whether the new version will break your project or not.
or the smart guy regretting that hugo do not use his prefered tool.
I tried Hugo, and Jekyll and my biggest gripe with either is the Markdown format. I prefer RestructuredText and it is truly a superior format.
All genius experts full of their own certitudes. Reminds me a lot people who find normal to reinstall a PC Windows just to get a sense a better performance after some time. Mind is a powerful prison. I hope for them they didn’t learn sex the way they try to learn hugo.
Resources are a big deal. I encourage you to donate to their project.
The fact that I started 4 months ago and it’s already moved from 89.4 to 93.0 with quite a number of improvements and the community here responding so quickly to posts I make here help highlight why they deserve it.
The community/devs make up for any shortcomings in docs.