Frustrated with documentation

Hi, everyone. Please take my comments in the nicest way possible. I mean, I understand what I’ve paid for Hugo and I respect the time and effort that the developers have given.

I really want to like and use Hugo, but I am very frustrated with the documentation. Especially the documentation involving anything that lives inside the mustache brackets {{ }}. The information that is necessary for someone that is new to this to understand is scattered across multiple pages and incomplete. For example, can you tell me the difference between IsMenuCurrent and HasMenuCurrent by reading the documents? Can you show me a reference in the documentation showing a list of keywords kind of like MSDN with hierarchical information?

I have spent over 4 days bouncing around inside the documents and forums trying to piece together things that I need to get a basic website with dynamic menus going, and while I have some working examples of things, I lack the deeper understanding that would be necessary to make good designs. I’m sure that eventually I can get this understanding, but with how things are organized it will take a long time. Understand that this is coming from someone whose day job is programming (the website I’m trying to make is to offer tutorials and source code libraries).

I wish there were tutorials for Hugo like this one.

Thank you for reading this and I hope that it is received as constructive feedback. Hugo is advertised as an easy to set up and get going software, but there is a real barrier to entry when it comes to being productive, and I think it’s because of the documentation.

2 Likes

@rewind I can see you are frustrated, but you’re criticism of the docs is pretty high level. I’m not saying it’s wrong, but can you expand on some more specific things you’d like to see to make the doc content more user-friendly to beginners?

As for the tutorial for Jekyll, keep in mind that it is just that: a tutorial. It’s different than documentation, although I appreciate how Hugo might be frustrating to a new person. That said, more concrete examples might help in making progress…

Moving conversation from Hugo Issue 1504

Anything beyond the very basic implementation as seen in the bulk of the themes available is difficult to understand and, at least in my case, impossible to implement. Taxonomies, nothing works. Menu, nothing works. By nothing works I mean that when I try to use the code shown in the documentation, the resulting html is empty with no errors. I have no idea why. I have read through the documentation three or five times now. There are key pieces to how things work that either I am not getting or they are missing.

The directory structure shown on the overview source-directory page was an “ah hah” moment. Seeing what a fully populated layouts directory might look like gave me some key bits that I did not pick up in the documentation. I am still not completely sure what should in those directories in terms of files and file names. I will continue sorting it out through debugging methods to figure it out. In another discussion here someone mentioned that they finally downloaded the source code and reverse engineered things by reading the source code and following code threads.

I really think that including a fully implemented directory structure, with all of the template components would really help in understanding how Hugo expects the directory to be. Incorporating some of the explanations from the documentation as comments in the source files would make it a lot easier to understand how things work.

As I continue my journey to understand how Hugo works I will probably build such a directory. If I do not get frustrated and give up first, I will be happy to refine it and submit it as a theme/template. Might be a while though. Figuring Hugo out through debugging is slow, tedious and frustrating.

I really want to figure Hugo out. This is really the way I would like to be creating my content, managing my web property, and integrating the content. I really would like to get over the hump.

…Smittie

3 Likes

@rewind, two months on what have you figured out and what guidance do you have for someone traveling a similar path.

…Smittie

1 Like

And, to make matters worse, critical directory names are incorrect in the examples. On the Source Organization example it shows layouts–>taxonomies. I spent two hours trying to figure out why the templates I put in there were not getting used. Turns out, the issue is that Hugo is looking for taxonomy, not taxonomies.

A sample directory structure with all of the template names that Hugo knows how to use by default would be helpful in figure out how it works.

On the positive side, as I make progress in figuring Hugo out I get more excited about what it will mean in terms of what I can do with it.

…Smittie

As it turns out, what I was looking to accomplish was even easier than I thought. Add a terms.html to _default and it works exactly as I was looking for. I’m really liking Hugo. I just wish the documentation was easier to use and understand.

…Smittie

The good thing about Hugo’s documentation is that it is easy to change … and as Hugo is an open source project built for and by the users, you can fix it yourself if you want.

1 Like

I am willing to make some contribution of effort. I would like to make sure it is in with what everyone else is doing. For me, the documentation would be a lot easier and faster to comprehend if it was more like what the author of html5up.net does. Documentation of us and functionality is embedded in the templates. Comments in the template source explain the function of that particular template. The end state would/could be a theme that serves as documentation.
…Smittie

I am brand new looking at Hugo and GitHub. I have looked at the https://gohugo.io/overview/quickstart/ video and I can’t even figure out how to duplicate more than the first few steps. I have installed Hugo and GitHub. Is there a guide or video that will go through the process of making a simple web page? I can duplicate the commands up until he uses a dollar sign. I am in windows 10 and it does not recognize a $ in a command line. Any help is appreciated.

What command is using the dollar sign? In the future, don’t hijack an old thread. Start a new one.

$ git clone… 22 seconds in

@JoeLav There are certainly some assumptions made by both the documentation and the associated video. If you are hung up on the git clone phase and the bling, you might not be familiar enough with the command line. If you are using Windows, download Git and git bash and perhaps take a tutorial on git first before going into developing sites, even with SSGs. You will never regret understanding source control. Best of luck!

The dollar sign is the command prompt. It’s not a part of the command. It’s like C:\> in Windows.

1 Like