ChatGPT filling in the gaps. Also, what is `{{ }}` called?

[merchako]

As someone who isn't already familiar with Go and Go Templates, the Hugo docs have been a struggle for me, and StackOverflow hasn't been sufficient to fill in the gap. One of the problems is that it's hard to get the right vocabulary to ask for help, even if it is out there. For example, take my most recent question:

Is it okay to have line breaks within… one of those {{ }} statements?

I didn't know what to call a {{ }} statement. Neither did Hugo Docs. This is how they're introduced

Golang template variables and functions are accessible within {{ }}.

And as far as I know, they're never defined further. Even a search for {{ }} returns rubbish, as does what I eventually learned was their term, "action". I didn't fare better on search engines. How did I find out that they're called actions? Chat GPT.

So I've had a few takeaways:

1. Keywords are important in documentation (and error messages!) to give users vocabulary to find additional help.
2. Brevity is admirable, but Hugo Docs can be frustratingly brief
3. Hugo Docs dominate search results for Hugo questions, so Google and reading the Docs aren't all that different, but
4. ChatGPT provides a completely new pathway to seek answers for Hugo questions.
5. I'm still not 100% sure whether I can use line breaks in Go template actions even though ChatGPT said I could.
6. Even if ChatGPT is wrong, it's easier to find out if it's wrong than to answer my original question.

[bep]

Even if ChatGPT is wrong, it's easier to find out if it's wrong than to answer my original question.

I'm not sure if there is a question raised in this issue. I agree that ChatGPT is mighty impressive and

1. The language/prose is very impressive and to the point, and in many ways better than what we currently have in many places in Hugo Docs today (we do, however, work on a new and refreshed docs site)
2. But, ChatGPT also uses that same confident language on stuff it does not understand/know, which becomes problematic very fast. The devil is certainly in the details when it comes to Go templating, and I have tested some Hugo questions on ChatGPT that, to me the expert, is obviously wrong, but to beginning Hugo user that same answer would lead to hours wasting in "why doesn't this work?"

[jmooring]

@merchako

In the Introduction to Hugo Templating, at the top of the page, we have this callout:

Which links to: https://pkg.go.dev/text/template

Which describes {{ }}:

It seems likes the link to the Go docs is prominent, but I am open to suggestions.

[merchako]

Yes, both of your points capture what I'm experiencing. Well, really, all three, because

1. You're right that I didn't raise a clear question, which captures how I often feel when trying to learn. I can't figure out what my question is, and in a space like StackOverflow, mods have been vicious—shooting down earnest and open-ended questions. So ChatGPT has actually given me a space to ask for help without a clear question and without risking that kind of exposure.

2. How great would it be if we had that kind of prose, and

3. I appreciate that an expert like you can see when ChatGPT is obviously wrong. I suppose that's why I brought this experience here.[^1]

My desire is for us to have that better documentation, and to help even though I'm a novice—not merely to complain.

Hence the question

How might a novice like me help make Hugo better even though I don't know much. Is this a way forward? Might I start with asking an AI until I think I've found a gap, and then pass it on to the experts for them to do the (presumably much easier) work of saying whether it's obviously right or wrong?

For example

ChatGPT told me that I can use line breaks within Go Template actions. I did so, and I got a parse error. So I asked ChatGPT, why? Because Go Templates don't support the Map function. And so on…

I didn't mention that earlier because I haven't gotten to the end of that inquiry yet. But I have two clear assertions from ChatGPT that I can bring to expert humans or confirm with more targeted searches in the documentation. Is it true that…

1. Go Templates don't support Map, and
2. Line breaks are allowed within Go Template actions? Is the whitespace within this dict valid?

   {{ $state := .Params.state }}
   {{ with (dict
       "open" "partials/open"
       "closed" "partials/closed"
       "pending" "partials/pending"
   ) }}
       {{ $partials := . }}
   {{ end }}
   {{ $getPartialFunc $state $partials }}

[^1]: And maybe this wasn't the best place; I didn't notice a more appropriate forum in my searches.

[jmooring]

I didn't notice a more appropriate forum in my searches.

We prefer to use GitHub for verified bugs and (somewhat) vetted enhancements. Discussions, questions, and troubleshooting are better suited for https://discourse.gohugo.io/.

[merchako]

Didn't see callout to Go docs

@jmooring, thank you for pointing out the link to the Go Template docs. Curiously, I didn't even notice it while referencing the page for this post. It might be attributable to kind of banner blindness.

You might consider mimicking MDN's styling for the warning and info boxes (example in red and blue). It would also help to front-load the advice to read the Go Template docs—and be specific: Go is a big topic.

Before

The following is only a primer on Go templates. For an in-depth look into Go templates, check the official Go docs.

After

Read about Go Templates. Hugo templates are Go templates with built-in variables.

It's also not clear what the difference is between Go and Hugo templates, if any. You mention the built-ins, like .Title and the section on Hugo parameters, but is that the conceptual difference? If so, consider saying it at the top.

Can't depend on Go docs

Nonetheless, I've been in the Go Template docs before, and I find the Hugo docs to be significantly more readable. It took me a bit of re-reading to parse your quote defining actions. I'm not sure you can depend on the Go Template docs to explain important templating concepts and vocabulary for you. I searched for "actions" and {{ on the 'Go docs' page linked to in the callout[^2] (Discover Packages > Standard library > html > template), and both terms are used without defining them or giving enough context clues to figure them out.

The difference between that page and the one @jmooring linked to with the description[^1] of "action" is very subtle. Both are titled "template". The latter happens to have "text" in its breadcrumbs rather than "html".

[^1]: I'm hesistant to call it a definition because it's only a phrase, "data evaluations or control structures", injected into a sentence about syntax. [^2]: Update: I'm not sure where I got this link, but it was easy to get. Which is to say it was the one already up in my browser as I was writing this comment. It also took me a while to notice that it's different from the one linked to in the callout. So case in point? 🤷‍♂️

[xbc5]

That is an absolutely terrible description -- it's vague and awkwardly worded. Documentation needs to be concise:

Templates use UTF-8; {{ }} are called actions, and they MUST wrap all syntactical elements -- for example: ....

Another thing is when trying to keep documentation DRY, we end up linking (delegating) causing the reader to switch contexts and hunt for answers. Sometimes it's better to write a small (~50 word) paragraph, covering only a majority of the fundamentals, or common issues. The external documentation is there to cover the details.

[jmooring]

This isn't actionable.