NEW DOCS SITE! Need feedback!

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

Thanks for the kind words, @verythorough. (Nice username, btw :smile:). I think everyone is going to like the new and improved visual design that @budparr is working on as well.

WTD is something thatā€™s intrigued me for a while and seems right up my alley as a documentation freak. Were you at the Portland conference a week and a half ago?

2 Likes

When I started using Hugo there was one thing I really hated: EVERY tutoriel starts by downloading a theme. (Without any explanation what themes are, what theyā€™re good for and how to write your own ones.)

I would like to have clarification in: why you donā€™t need to build a theme when writing a website, how hugoā€™s markdown system works, a little guide in using layouts, overriding parts of a theme and writing your own theme.

1 Like

like the new docs site pretty much. has become my standard docs site. great work!

1 Like

Somehow I missed the notifications for these replies.

@rdwatters, WTD is great! I did go to the Portland conference, and found it very worthwhile. Their slack is pretty active, as well. Weā€™ve been talking about Hugo in the #static-site-generator channel. Lots of developers/documentarians doing cool stuff with docs!

1 Like

The ā€œImprove this pageā€ link goes to 404.

The example on https://hugodocs.info/functions/sort/ does not work for me.

The output is empty.

Generally I have a problem to understand the difference between ā€œmapā€, "array and ā€œsliceā€. I know Python a little so I am more familiar with lists, dictionaries, tuples.

And I get confused by the usage of key and value on this page.