NEW DOCS SITE! Need feedback!

The documentation is indeed a core component of Hugo (from a users perspective) and in general for software libraries / frameworks / APIs…
It’s not that easy to create a documentation which is extensive and covers the functionality and at the same time is easy accessible and a user can find what he needs in a short time.
Working as a framework developer, I mostly struggle in the second part which means more L1 support requests from users with answers pointing to existing documentation.

2 Likes

I discovered Hugo about year and a half ago, but have only managed to create one semi-useful website. That was basically a placeholder until I get the proper site done, and just stated work in progress. http://finecoline.fi/

These new docs seem lots better, but I still can not understand how to get what I want with hugo. This weekend I thought I could make some headway with the new documentation and create a site where it does not matter much what it looks like. Seems I can organize my files to directories in content/, but to make that into a useful site I need to write a theme myself.

I tried hugo-theme-robust and hyde-y. Hyde-y looks promising, but to get the navigation I need to write it myself and guess how to write the URLs there to get to the files.

robust was more useful, but seems I broke it by using hyde-y theme. Going back to hugo-theme-robust makes a website that looks nothing like what I got the first time.

I copied back config.toml from before hyde-y, but still strange looking site. Surely there should be a way to write theme specific configurations to some theme specific file, so it does not break settings for other themes.

Is it necessary to make hugo new for each theme, and maybe link the contents -directory to all those?

Hopefully documentation gets a good set of instructions on creating a theme, and maybe how to modify a theme.

I think what I most need is a tutorial explaining how to use hugo to create a nontrivial website. Say content has tree directories and a few files in each. Or maybe teach the hugo way to construct a website.

Is there a mapping from HTML and CSS stuff to Hugo primitives? So if I know how the site would be like if writing HTML and CSS, I could see how to do the same with hugo?

Thanks for the feedback @Taleman.

My immediate reaction to this was that you’re probably right, but at the same time, even when browsing themes on ThemeForest for Wordpress, I always think to myself that I should just write my own.

I think the results of your search will improve as the number of themes increases…since the fact that you’re not finding what you need might just be a matter of it not being there.

Where do you see this theme file living? If it’s in the theme itself, what about changes to the upstream? I think this may seem like a good idea at first, but the idea of theme-specific configuration files (i.e., rather than just having the author include a good README.md [and we are improving this area of the documentation]) actually makes the theming capabilities less flexible since you’d be tethering the output and content of your site to a single theme rather than treating all your content and configuration as something separate.

You could go the route of a having a much stricter, really long set of site config variables, but I’m not sure how you could account for every type of site. Plus, this would be a nightmare for international users who speak English as a second language. You could make the data/content model more narrowly scoped, but then you have a Wordpress problem (i.e, everything is a “post” or “page”). I agree that these things should probably be easier, so I’m throwing out some ideas :smile:

The new docs are improved but far from perfect. I’ll certainly continue to iterate and add to the installing and customizing pages under “Themes.” If you can provide me some more specific feedback or even open an issue, I’ll do what I can.

I empathize with you, but the truth is that a “tutorial explaining how to use hugo to create a nontrivial website” will likely never be part of documentation. This isn’t a Hugo-specific sensibility. In the couple dozen SSG projects I looked at during my content analysis, almost none have any real substantive tutorials in them (outside of a few impressive Quick Starts). This is why so many OS projects have cottage industries built on top of full-length tutorials for beginners. For example, I spent $80 on a React Tutorial a year ago because the docs weren’t getting me quite as deep into what I wanted to figure out.

In fact, https://hugodocs.info doesn’t have a “tutorials” section at all, and this is for good reason: Hugo is changing (read: improving) constantly, and the old tutorials section was, quite literally, outdated in every single page. Instead, I think it’s best to structure the new version as logically as possible, promote cross-linking, be fastidious about documenting undocumented (but still supported) and new features, and provide examples, examples, and more examples. Maintaining a comprehensive tutorial would be nearly impossible with current staffing, and also just an ineffective means of managing content for this type of site.

Hopefully the new and continually improved docs help you in this effort, but I think part of the appeal of Hugo is its flexibility.

NB, I plan on creating an entirely new quick start as soon as the community can come up with a default “theme” for Hugo, but I don’t think it will be part of the first launch of the new docs site. The current Quick Start was great for v15, but it’s way too end-to-end (speaking to your point of tutorials) and walks through what I see as a less-than-popular use case.

I’m not 100% sure on what you’re asking, but I believe the answer is just “no.” For one thing, Hugo doesn’t deal in matters of CSS at all, at least currently.

Keep coming back to the forums and reaching out to the community. I’m sure someone will be able to help you :smile:

1 Like

Error messages. Translating the Go template errors into something readable by non-Go-template-developers. Hugo’s come a long way, but we still have messages like:

ERROR 2017/03/19 17:03:42 Error while rendering "page article/2012.md": template: theme/article/single.html:68:8: executing "theme/article/single.html" at <.>: can't give argument to non-function .

The helpful thing here would be a list of “commonly encountered error messages” and gentle hints. The danger, of course, is that they can go stale.

The weakness is that when you don’t know what to search for, you can’t find what you’re looking for. I know that’s kind of nonsense, but a beginner needs to be able to find concepts and have them located near to each other rather than spread out over a few pages.

An example would be “how can I show some number of recent documents but not the current one and also filter the results?” Once you stumble on range and where, the rest of the answer is easy (well, less hard) to puzzle out. But getting to there requires searching the forums, finding an answer that works on the current version of Hugo, and trying to tie the concepts together:

{{ range first 5 (where .Site.Pages ".Params.show_in_recent" true) }}
	{{ if ne . $ }}<li><a href="{{ .Permalink }}">{{ .Title }}</a></li>{{ end }}
{{ end }}

No, I don’t. It seems to cover everything.

I’d start out by assuming very little experience with Go templates and scripting. It’s weird because I’d have supposed that techies with large sites would be the target but it seems that people are pulled in because of the speed. I’ll admit that Hugo is easier to use than almost anything with Ruby, but it is markedly different than anything “popular” (such as WordPress).

I almost forgot - I love the page for lists - https://hugodocs.info/templates/lists/#what-is-a-list-page-template

2 Likes

I do agree that a common errors page would be useful. See this issue at @rdwatters repo. I have a couple questions:

  1. What is the best way to figure out which errors are most common?
  2. The search on the concept site is fantastic; what would be the best way to catalog errors without cluttering the site and improved search functionality?

Actually, nothing nonsensical about it. I think you perfectly captured my thoughts on this page of the current site, but I’m assuming mynonsense == yournonsense. The _index.md feature was actually an awesome improvement, IMHO, but nobody could have known to look for it…and they still don’t. My hope is that the current order of the pages/nav makes a little more sense, but I think analytics and really putting it out in the wild is going to be the real judge of that. Search is considerably better now, but to your point, you have to know what you’re searching for.

I think the “concepts” piece is really the job of the Quick Start. As for searching the forums, I think one trick to get them there in the first place is a quick, sexy, hey-look-at-how-fun-this-can-be-in-10-minutes walkthrough of Hugo. After that, it’s easy to lose newbs, for sure, but like anything else, we can only motivate people so much.

Agreed also. FWIW, I don’t know a darn thing about Golang other than what I’ve read recently because of recommendations from the team. I think Hugo does a decent enough job of this already. This is an empirical statement rather than a scientific one, but I think one reason users of SSGs assume it’s going to be more difficult is because they think the syntax is wildly different. However, I don’t think that’s the case…but I also use it every day…and so I’m entirely biased.

Really? Thanks man! I think the visual helps people understand the concept, but I’m going to have to find a designer friend to make it a little less offensive to the eyes.

As an aside, I was planning on reaching out to you directly because (I believe) you wrote the tutorial to help people get up and running. It was comprehensive, well-written, and did a fantastic job at using plain language to explain Hugo concepts. I hope what I said above re: tutorials demonstrated that the decision to omit them [the tutorials] in the concept site was only a matter of maintainability and not quailty :smile: Thanks!

tl;dr;
To both your questions, @sethm, I really don’t know, but I’m open to suggestions :smile:

That is a very good question. Unless you have a feedback mechanism built into the tool itself that sends errors to some type of log, the “common” piece is going to be largely qualitative, which isn’t always the best approach to docs/publishing. Now that I have access to GA, hopefully I can make some more data-driven decisions…

And do you mean “errors” as in “common misconceptions for newcomers” or do you mean “errors” as in “mistakes new users make that they assume Hugo should account for or possibly have written to the terminal”?

I would hope we would never have enough pages for errors that it would somehow bloat search. From what I’ve gleaned, the Algolia doc search is actually pretty simple: just have to keep your heading structure consistent and intuitive.

That said, the previous “troubleshooting” section was out of date almost across the board, so out-of-date results are worse than no results. In my experience, adding pages is never really the problem – it’s deleting them once they’re outdated. If users find they have a lot of equivocal/confusing/strange errors repeatedly, the best thing to do is to file an issue (if the community can’t help resolve it). Unless someone knows of a more granular way to tag threads/complaints/concners in these forums…

OR you could take the route of trying to document every error people report, but this will cause a tremendous amount of bloat on the site, and to @michael_henderson 's point, you want to keep the docs as simple as possible for users new to the project/product.

In a future, ideal state, the Hugo docs should (or could) have a nice version-based interface—(think of something like Ember—but that will require a whole slew of iterative improvements.

I come from a communication/marketing background and lack some development skills, so please take what follows with that in mind. The focus is on content and not how the docs are structured.

First, the challenges.

  • When reading the documentation it was fairly easy to find what I needed to port a template to a Hugo theme. The hard part was figuring out where the files should be placed.

  • Some concepts where not straightforwad. It took me a while to figure out the Taxonomies could be defined by me and didn’t have to be limited to categories or tags.

Second, the opportunities.

  • as a CMS Hugo looks as flexible as an acrobat! I used quite a few things that @bep shared here in the forum and github to configure the search and some other features.

  • I wanted my own meta tags, so I searched the source code to replace some of the internal templates and make them more flexible.

Third, solutions and suggestions.

  • For the getting started chapter, it could be valuable to add a few paragraphs on how Hugo as a few concepts that distinguish it from other CMS and a brief explanation. These could be taxonomies, archetypes, content structure, and static directories.

  • Add a glossary of terms. What is a taxonomy, what is front matter, what is the Scratch feature, etc.

  • For themes, either provide the blank version or guide the user in creating a blank theme.

1 Like

@brunoamaral Thanks for the feedback!

Just to clarify, are you talking about the current docs (gohugo.io), the concept site (hugodocs.info), or both?

For the record, I consider myself a publisher/content strategist first and a developer (maybe) second, so your feedback is exactly what I’m looking for.

I like the glossary idea as well. Did you find the new functions Quick Reference added any value?

As for Getting Started, I think you’ve provided some great feedback for things we should keep in mind as we rework this section, especially the Quick Start.

As time goes on, please feel free to provide more feedback on the docs directly through this forum, Github issues on the docs repo, or even DM me if that’s easiest. Thanks!

It applies to both. I only took a quick read through the new docs and it appeared to have a similar text and changes in structure.

The functions quick reference does help, and points towards a problem that would rise from using a glossary. There needs to be a clear distinction between what are concepts used in Hugo and static site generators and what are the functions people can use in their templates.

1 Like

I’m with you - I hate going through docs and having outdated tutorials getting in the way of answers…

Would it be helpful to put tutorials etc. to the forums under “tips and tricks” - at least then they can be dated, versions can be noted and still semi maintained by the community. There’s still relevant information that can be gleaned and changes could be easily noted as both replies and other tutorials. Step 11 under the quick start could then note that there are tutorials in the forums and they can ask questions to help them take things to the next level.

Example:

  • Customizing my new portfolio site in 10 minutes ( v18)
    • disclaimer: This is a Hugo v18 tutorial. Replies are for alternative suggestions, or commentary. If you complete this tutorial and have errors, or questions, please do not reply here. Search the forums, or create a separate topic using the support category.

Step 1: Custom Taxonomies

@justrjlewis This is also great feedback and thank you!

I think there is definitely room for improvement in the forums that will hopefully come in the future, but for right now I’m just trying to focus on what should and shouldn’t be in the documentation. @budparr is currently working on what might be a news/blog/etc section of the future site, which I think would be a great place to have some select, community-contributed, dated, and versioned tutorials for Hugo.

Variable scoping. I was planning to write an explainer as soon as I get my head around it myself.

EDIT: is variable scoping behaviour due to the design of Hugo, or is it due to the Go html/template engine?

Also, the fact that nested shortcodes render from the inside out, so you can’t use a Scratch var to pass a flag from the outside shortcode to the inner shortcode. See Passing Scratch flags between shortcodes - support - HUGO

1 Like

Beautiful design; much nicer than the old site.

Here’s my beginner problem: I have a site working using the hugo-material-docs theme.
Site: www.WinterTechForum.com
Github Repo: https://github.com/BruceEckel/WinterTechForum

I’ve tried both the old and new documentation, and I’ve been unable to find out basic information about setting up the next/previous links at the bottom of each page. By guessing, I figured out that you apparently need to use weights for both the config.toml and each individual index.md file (although I haven’t tried putting weights only in the index.mds). And it works OK except for the final page (https://bruceeckel.github.io/WinterTechForum/contact/#support) where I’d like to have no next at all, but for some reason it produces a pluralization of the page starting with “A” and I’m sure that’s part of the taxonomy.

I came across one post that said you can use next: and previous: in the header but that seems to no longer work.

So, it would be nice to have more information about that. Thanks.

1 Like

Hi, small tiny request: May there be a scrollbar next to the page? The long document pages can be easily scrolled to the desired location using a scrollbar. Currently there are no scrollbars and it’s a bit of a hassle to scroll with mouse and with keyboard requires many keypresses.

4 Likes

Do you still take docs feedback, @rdwatters?

If so, I think the docs will benefit from clarifying what “page” means, since it doesn’t mean “HTML page” or “rendered webpage”.

For instance, .Site.RegularPages is, according to the docs a “regular page collection”, but I learned it can also contain non-HTML files.

In other platforms, a “page” is often a HTML page so this might be confusing to other people too.

HTH.

1 Like

Hi @rdwatters, the search is not working for me on all pages. On where, for instance, I can click the search icon and start typing – and nothing happens.

Firefox developer tools say:

07:45:38.950 ReferenceError: docsearch is not defined 1 where:687:1
    <anonymous> https://hugodocs.info/functions/where/:687:1

Oddly enough, on the creating a theme page search does work for me when using the same browser.

Edit: On the ‘creating a theme page’ search now doesn’t work after a page refresh. It seems a bit random now.

Should the docsearch function be called with async defer? Not sure if initialising docsearch() asynchronously from loading the Algolia docsearch JS (docsearch.min.js) works the best.

@Jura

This seems to be an interstitial issue with doc search but doesn’t appear to be anything on our side. You’ll see I made a comment the last time something like this happened:

https://github.com/algolia/docsearch/issues/175#issuecomment-289511435

It’s working on my end as well, so I’m guessing it should be back up and running shortly…

1 Like

@rdwatters I’ve found these docs extremely useful. I’ve shared them with many others (including the Write the Docs community), and all agree they are night-and-day more helpful than the official ones.

(Basically, my current answer to “Which SSG should I use?” is generally, “Jekyll has better docs and support, but dealing with Ruby versions can be a huge hassle. Hugo has a much simpler install process and builds faster, but the docs are pretty unhelpful… UNLESS you try the new ones at hugodocs.info!”)

The Write the Docs community in particular has reacted very positively. Is there anything we can do to help advocate for making these the official docs? Some may also be interested in helping make content contributions.

1 Like

They will be the content foundation of the new docs, but it has taken us longer than we’d hoped to get there. We are working on some structural GitHub changes to more easily manage all the Hugo sites (and delegate the work, i.e. access rights etc.). It is coming.

3 Likes