New docs content structure

[bep]

Reference

• Markup
  • Configuration
  • Render Hooks
  • Shortcodes
  • Front Matter
• Hugo Modules
  • Configuration
  • Imports
  • File Mounts
• Components
  • archetypes
  • content
  • static
  • layouts
  • data
  • assets
  • i18n
• Objects (interfaces)
  • Pages
    • Sorting (ByWeight etc.)
    • Grouping
    • Pagination
  • Site
    • Methods
      • .Pages
      • .RegularPages
      • ...
  • Page
    • Methods
      • .Kind, .IsPage, .IsNode
      • .RelPermalink
      • .Pages
      • .RegularPages
      • .RegularPagesRecursive
      • ...
  • Image
  • Resource
  • Menu
• Function namespaces
  • cast
  • collections
    • .Append
    • .Complement
    • ...
  • diagrams
  • resources
    • .Match
    • .GetMatch
    • .GetRemote
    • ...
  • strings
  • ...

Configuration

Templates

Lookup Rules

---

We should try to

• Keep the reference section mostly auto-generated so it's in synch with the code.
• We can create some naming scheme or something for the cases where we cant to add some more prose/examples to a given function/method.

[bep]

I will keep the intro post updated with my and others' thoughts about this. In this repo I have quickly (relatively) converted the old theme/site to a more modern stack in. Whether this was a great idea or not, I'm not sure, but I have had a few failed attempts building the old one (been looking at at non-fatal GitHub security report that I have not been able to fix), telling me that we at least need to do something.

I have been thinking about what to do with the content part of this. The preview build here currently builds the entire old docs content with some slight adjustments (documentation is now mounted below /documentation -- https://gohugoiotheme.netlify.app/documentation/), but ...

My take on this is that we need to somehow start fresh. It's lot of great content in the old, but it's much harder to remove/move stuff compared to re-adding stuff into a new structure.

So, I suggest that we 1) Agree on a structure and 2) Create that structure and move articles from the old repo.

/cc @jmooring @coliff etc.

[coliff]

Happy to see work on the 'new site theme' project picking up again!
Just had a quick look at the Netlify preview and it's looking great. Impressive page load times too - it's lightning fast.
I'd be happy to contribute some time to work on a few things on it tomorrow. I'll take a deeper look at the content and will post back if I have any thoughts to share on that side of things.

[rsolvang]

So, I suggest that we 1) Agree on a structure and 2) Create that structure and move articles from the old repo.

Totally agree. Are there any objections to using the Diataxis Framework as a high level structure for the docs? Some arguments in favor:

• Separating references from the other content into its own category makes it easier to keep it up-to-date by auto-generating the content based on the code.
• Lowers the bar for community members to add how-to's and tutorials, as these will stand by themselves and are not too intertwined with the rest of the docs (only linking to references and explanations where needed).
• Making it easier for newcomers to look up / search for explanations on specific aspects of Hugo.

[bep]

The Diátaxis makes sense (not so much the name they have chosen, though). I suspect much clarity will come from getting a solid and simple Reference section. Earlier today I tried to find the documentation for resources.Match to link to in an issue, but didn't find it (I added some ...). The interface declarations in the Go code are always up-to-date and precise, so we can get lot of value by using that directly.

With that, ref Diátaxis:

• The Reference, section will be mostly redone from scratch (and much less verbose than what's currently there).
• With that up and running, again according to Diátaxis, I think it makes sense to also create a Explanation section -- which can be referenced to/from.

[rsolvang]

The current docs mostly fit into the reference and explanation categories, although intertwined. I think that a lot of the existing content can be reused for the explanation category, although with some manual parsing and touching up to fit the new structure.

With that in place, the how-tos and tutorials can be written, covering specific use-cases. This is where we need input from the wider community, asking what we wished existed back when we starting to learn Hugo from scratch. Having written (most) of the reference and explanation material first, makes it possible to link back to the "dry" documentation from the how-tos an tutorials.

This could go both ways; the reference and explanation docs could contain a "further reading" section, listing related docs like how-tos ant tutorials based on tags or custom taxonomies. I believe something similar is done in the current docs?

[bep]

I have started some work on this here: https://deploy-preview-14--gohugoiotheme.netlify.app/documentation/reference/functions/math/

Main ideas:

• Left navigation entirely driven by the section tree.
• Inter-section navigation driven by Hugo's Related feature and taxonomies.
• The Reference section (structure) is autogenerated and in synch with the Go source, but can easily be manually expanded (with bundle backing files) (and there are obviously some cleanup to be done in the Go source)
• As long as the Reference section is correct and we maintain some discipline when tagging content (adding keywords for the "More Explanation" (See Also) section), it doesn't matter too much where people put stuff in the other sections.

[rsolvang]

This looks great! I hope to be able to write some Guides and/or Tutorials covering some topics that newcomers often struggle with. I have also been working on a little deploy script that I can make a guide for under the "Deploy" section, when my script is ready for general use.

[jmooring]

@bep This is looking really good. Regarding the Go source for method description...

Sometimes the Go source describes how a method works from an implementation perspective, but that might not be the best way to describe it to a site author. For example, collections.Merge...

Go source

Merge creates a copy of the final parameter and merges the preceding parameters into it in reverse order. Currently only maps are supported. Key handling is case insensitive.

Current documentation (I made the change here due to #1641)

Returns the result of merging two or more maps from left to right. If a key already exists, merge updates its value. If a key is absent, merge inserts the value under the new key. Key handling is case-insensitive.

I dislike the idea of maintaining two descriptions (source + override), but I'm not sure you'd want to change the source description either.

[bep]

@jmooring so, I'm open to ideas about this, but the main point (or one of them) I'm trying to address with this is completeness. I answered a few hours ago some question in the docs forum where I said "use $image.Key where he replied "Is this in the documentaion?" and I answered "... probably not".

Note that in the math example above you could override the description by adding a Markdown file with a certain name, which would be the option in many cases (e.g. resources.GetRemote). But, as part of this we definitively should rework the GoDoc comments. I did some experiments with this making sure the arguments had a sensible name, and I would not mind giving the GoDoc comments
a format that's suitable for the web. We could even consider JSON or something if needed. Again, my main point is to get back to a more complete documentation.

[bep]

To make my point clearer -- I just pushed an update with all the template namespaces. There still are some functions that show up empty, but it's certainly more complete than what we have:

https://deploy-preview-14--gohugoiotheme.netlify.app/documentation/reference/functions/math/

My main point about this is to get the structural parts complete -- I do understand that (most of the) prose needs to be written in Markdown, and we should encourage that (adding "edit this") links.

[bep]

OK, @jmooring I have been skiing today (downhill), and the cold weather cleared my mind on this a little. The main things this "auto doc" of the template functions (and then also the methods on Page etc.) was that of 1) Structure and 2) Completeness. Once that is in place it should be a pretty stable structure (we sometimes add new functions, but rarely change or remove).

With that in mind I think there are lots of value in having it mostly what you see is what you edit.

So I suggest we (or I) create a script that creates the new structure. Then we can copy in the prose from the old structure bits by bit.

I still suggest that we keep it 1 page per namespace. If people want to write in long form about a function, that belongs in another section.

[chrisreddington]

@bep - Great to see the direction with the new theme, and particularly the cleanliness / clarity of the docs - I'm a big fan. Like @rsolvang, I'm also happy to contribute examples / how to guides once the time is right.

I'm not sure I can contribute much to the site changes, as you look to have this well-covered - but I'll keep watching this repository, in case there is something I may be able to contribute.