Proposal: HugoDocs Guides

[budparr]

When I speak to people about Hugo the number one request regarding documentation is for more examples.

I fact, I was thinking of somehow adding @regisphilibert's post on Scratch, and perhaps others, to the docs and thought it may be too much information for the initial documentation page, but would clearly work well on its own.

I suggest a new section for the docs called Guides (or whatever, maybe examples?), which roughly resemble blog posts (In fact, they could be news items, flagged with a category of guide and linked to in the docs), or sets of contributed examples.

I think this will allow us to elaborate on concepts in the docs while keeping the docs pages succinct.

cc @bep @regisphilibert @rdwatters @digitalcraftsman

[bep]

That is a good idea, but I think they should be clearly dated; we are not updating outdated guides from 3 years back. To do that we create a new one and link to the old one.

[budparr]

So do you think as news posts with a category, or their own section?

[kaushalmodi]

clearly dated

+1 + Hugo version used by the author at the time of writing too.

[bep]

I think the "news" section is maybe poorly named, but I think it work as a "announcement" kind of thing (releases etc.).

If we could create a new section with a slightly more general name than "quides" (i.e. user contributed content, howtos etc.). I'm not totally sure. I get a sense that the Gatsby people are doing something right in this area.

[budparr]

How about sticking with guides (I don't care, but it's seems to me okay) and make it very clear that it's submitted content.

I can see an issue with organizing things if we end up over time with multiple pages on one topic.
Perhaps we use bundles for this (Pardon my ignorance if I'm this isn't the right sort of use-case, just throwing this out there).

So

guides/scratch
     - contributor-name-or-topic.md
      - contributor-name-or-topic.md

guides/dates
  - contributor-name-or-topic.md

[DirtyF]

scratch and dateFormat are functions.

Why don't simply add real world examples to the relevant pages and/or add links to useful related articles?

Guides are most of the time task-oriented (how to…) Deploy to Netlify, etc.

[budparr]

@DirtyF See these sorts of posts for examples of what I'm talking about: https://regisphilibert.com/blog/2018/01/hugo-page-resources-and-how-to-use-them/

[bep]

Why don't simply add real world examples to the relevant pages and/or add links to useful related articles?

Because that creates an expectation of versioned accuracy (we have some of that today -- and it's not that it's not working (it is, mostly), but we have since then evolved and the "Hugo best practice" has changed. So we have to go back and update old examples.

Which is very time consuming for long articles -- which also does not fit into the more shorter "docs format".

@budparr I will sleep on this. Bundles worked great for the showcase -- mostly because it created a really easy-to-follow template.

[regisphilibert]

Hi guys.

I think it's a good idea, but wouldn't it be simpler for now to just have "suggested read" section at the bottom of some Doc pages. This would list external posts which GoHugo.io sort of approve or mark as good companion reads for a particular feature or topic.
There could also be a stand alone list page on the docs, where user can browse those "good reads" by category (as in feature, topic, function etc...)

Having GoHugo.io encourage the reader to read some external posts and somehow endorse their liability at a particular date and version while still letting the author keep responsability of content/evolution etc... seems easier and just as efficient as having GoHugo.io act as editor/curator of self hosted posts or guides.

My own two cents :)

[chrisdmacrae]

I feel like we should treat the Hugo “documentation” as a reference. This is how this functionality works.

Guides should be a clearly distinct section, that details how to do specific things with Hugo that solve a business or user need. In this scenario, anything that becomes out of date can simply be removed.

I believe this is the approach that Gatsby takes, but they strive to keep API compatibility so that an article doesn’t necessarily become “out of date”, but it may not be the most efficient way of doing things.

The idea that a guide needs to be the best way to do things isn’t necessarily correct. People just need to know how to solve a problem, and don’t care if it’s the perfect solution.

[rdwatters]

@budparr Double plus good on guides.

Yes to it’s own section.

“Getting Started” would be consumed in the guides, with installation being a separate item. I think Vue does the whole guide deal exceedingly well.

[kaushalmodi]

For the external guides, may be we can we have a Data file with URL, description, image, etc. for each guide. Then in the Guide's template, we just loop through those, and generate twitter-like "cards".

[bep]

This discussion is about guides served from gohugo.io. I'm pretty sure it is better to discuss one issue at a time (and not also how to handle "See also this external guide").

[Jos512]

Comment from @regisphilibert

Having GoHugo.io encourage the reader to read some external posts and somehow endorse their liability at a particular date and version while still letting the author keep responsability of content/evolution etc... seems easier and just as efficient as having GoHugo.io act as editor/curator of self hosted posts or guides.

I fully agree with this. As a content creator I don't like the idea of gohugo.io hosting guides that others published on their blog. From my standpoint, I post content on my website to show my expertise, just like @budparr does with the new Dynamic and @regisphilibert does with his blog.

If we merge that content like that on gohugo.io, a part of the attribution gets lost and the original website suffers in web traffic and search rankings. That's not a cool way to thank people for their work.

There's also an issue here about fostering a healthy Hugo community. To encourage people to write about Hugo, a small link from the Hugo website to their work can be highly motivating. Licensing their content and hosting it on gohugo.io is not motivating.

I'd much more like to see hyperlinks to other content around the web to encourage people to spread the word about Hugo more. It would also reduce potential confusion: the accuracy of external guides would remain the responsibility of the writer. And people don't have to make topics about "I got stuck with the guide on gohugo.io", just as we now already see with the quickstart guide.

I also wonder what the SEO implications would be that a high-ranking website (gohugio.io) publishes the same content as a smaller blog (regisphilibert.com). Search engines typically don't like guest posting with duplicate content, and can imagine that in this case the smaller blog suffers here.

If there's concern about using Google rank spillover from gohugo.io we can always link to external guides with rel="nofollow".

[budparr]

I must not have been clear about this. This is not (even slightly) about taking anyone's blog posts or linking to blog posts. It's about creating a set of examples or guides as an addendum to the existing documentation. I used Regis' blog posts because I wanted to draw examples from them, not take them wholesale.

Goals:

• Create a space to elaborate on principles in the documentation using examples.
• Keep the existing docs succinct.
• Allow for multiple examples/guides for any given topic.

[bep]

I believe this is the approach that Gatsby takes, but they strive to keep API compatibility so that an article doesn’t necessarily become “out of date”,

@chrisdmacrae A quick note to the above, for people coming here thinking that "Hugo does not". We do, even if the versioning scheme implies that we're still in development (which is also very much true). We make breaking changes only if we really have to (the index.md people may disagree). I think most of Steve Francia's Hugo 0.13 style sites are building fine with Hugo 0.37. And being one static binary Hugo does have an implicit API compatibility that the dynamic variants cannot match (try to get Jekyll 1.3 up and running).

But, I will assume that the "best practice" for any project of a certain size changes, even if old examples compiles/works. In the current Hugo docs there are of examples that I think could have been improved by the new resource/image/bundles etc. But they still work. But they become "out of date". This is true for Gatsby and other fast moving software.

So, the guides we talk about here are timestamped.

[kaushalmodi]

It's about creating a set of examples or guides as an addendum to the existing documentation.

If that's the case, then it seems like a difficult to maintain idea.. It would not be a clear-cut decision if something is "light enough" and should belong to docs, or if something has "more examples than allowed" and should be in the addendum.

I would vote to have everything in the docs so that there will be just one place to search for everything. As a user, I would find it comfortable that the where section in doc would have everything I would ever need about that function. As a contributor, I will be comfortable knowing that that's one .md file that I need to edit, and not go through Issue hoops to figure out where my content should live.

If the question comes to maintainability, grepping for obsolete code isn't too bad (that's how I deal with dead code in documentation at work). Each time something is obsoleted, just grep through the documentation and delete/replace as appropriate. I can help with that if needed.

If we go this route (one doc to rule them all), we can choose to have the summary of the docs in the beginning of each section, and then folks interested in examples can read further down.

[kaushalmodi]

Also, to help prevent obsoleted code in docs, we can have a mini test site full of snippets from the doc site that should always compile fine after each release.

[budparr]

one doc to rule them all

That's certainly a possibility . The impetus behind the proposal is to get more real-world examples on the site because it's a real pain point for people.

There's something to have one place as the place. However, right now we typically have, for any given "concept," a Content Management document and a Templating document. So, we don't have one place to start with.

The reason that I think a separate set of guides in place is that I think the documentation should be succinct. Any given example may or may not be relevant to a particular user, but there are a wide variety of uses for Hugo. Keeping these guides would allow us to jump off into topics that would dilute the power of the original documentation.

And, I think it would be easier to maintain—in that any given guide may or may not be relevant, just archive it instead of editing a longer document to figure out what may or may not be relevant.

[bep]

I fully agree with this. As a content creator I don't like the idea of gohugo.io hosting guides that others published on their blog.

That I agree with.

Look at this example:

https://gohugo.io/news/http2-server-push-in-hugo/

It is in the news section, but you will have a hard time finding it because it is dumped between the release notes.

The above is an example that is useful to many, but it is too long/wordy for the Output Format page in the docs.

We have seen a couple of iterations of the Hugo docs, and I have concluded that the best documentation is short and to the point with a simple English (we have users around the world). It is hard to find examples that are useful to most people, so these should also be short and conceptual.

This particular discussion is about something else, and it is also not about people re-submitting their blogs to Hugo or creating a link collection (which I'm not a big fan of). If no-one wants to write some content for the new section, that is fine, but we could start by moving the example above there.

[budparr]

@bep I mentioned you don't like the idea of using the news section for this, but perhaps we:

1. Call "news" something more generic, like "updates" or even "blog"
2. Use categories for "announcements" and "guides" (or "examples", whatever)
3. On the news page surface the categories so it's easy to see what's what.
4. Add the "guides" category to the docs.

The gain: more visibility for new guides as the come in, and minimal infrastructure added to this concept. Also, we already have dates and authors there.

The loss: the ability to do a bundles approach to organizing these (which I'm not 100% sure is good).

Keep in mind, everyone, the only thing I'm ultimately lobbying for is more examples. This thread is about the best way to accomplish that.

[regisphilibert]

I'm sorry misread the intentions of this issue @budparr. I agree some form of guides would be of help.

I also think a whole new section is a bit premature at this stage. The 4 steps @budparr listed above make a lot of sense to slowly introduce the guides and see if they take.
When there are dozens of "guides" up there, allotting them a new section may become convenient.

[Jos512]

@budparr

It's about creating a set of examples or guides as an addendum to the existing documentation.

That's a good idea, and thanks for clarifying. I quite misunderstood the angle of this issue.

(I also like your four step suggestion for how to implement this. Seems like a sane and good addition to the website.)

[rdwatters]

I like your original proposition @budparr . A common pattern is guides that are more tutorial like, narrative, and sequential in nature, and then API/reference documents. API/ref could—and this would be a longer term goal and I defer to @bep on the feasibility of it—rely more on automation (eg, comments in code) and just be quick chunklets of information (think of the difference between a language dictionary and a how-to guide).

https://emberjs.com is a good example.

I never took Bud’s original recommendation as means of copyright infringement 😉

[chrisdmacrae]

Another weigh on this, with a very good article on how to teach new users (with documentation):

http://stevelosh.com/blog/2013/09/teach-dont-tell/

[onedrawingperday]

Here is a tentative list of Guides that I could write if this category is agreed upon:

• Conditional Section and Nested Sections Menu (A standard Hugo menu that has different entries displayed by checking whether the .URL of the menu item equals to the .Type of a list page)

• Nested Taxonomies. My PR Add Docs for Nested Taxonomies #584 was not accepted in the Docs proper but this could be a Guide. There are some ugly hacks around the web to achieve this feature and it is requested by many.

• Generate Markdown Files from a single Data file with getJSON or getCSV and Hugo Archetypes. This came up in the Forum a few days ago.

---

If / when Hugo supports such features out-of-the-box (like for example when gohugoio/hugo#5074 is resolved) then Guides that are no longer needed, could be removed.

I think that there will be value in adding a Guides Section to the Docs.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If you still think this is important, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[rdwatters]

@budparr. What topics/problems do you think would be a good starter set for these guides?

A:

• Setting up responsive images
• The relationship between base templates and partials
• Creating lists from content and data files

Or are you thinking something more real-world-ish? The assumption is that these are lengthier.

B:

• Creating a blog with Hugo
• Creating a static eCommerce site with Hugo and Snipcart
• Developing Hugo sites with Tachyons (or Tailwinds,etc)

[budparr]

A

[rdwatters]

Perhaps the main content areas for Hugo become:

1. News & Releases
2. Docs
3. Guides

Defibrillating this issue in light of this recent conversation on the forum:

https://discourse.gohugo.io/t/hugo-101-slowstart-for-beginners/18383/3