Define an upgraded structure and sections for improving tutorial & how-to docs

[divinerites]

trafficstars

Following https://discourse.gohugo.io/t/has-hugo-become-too-complex/29609/41 and other threads (https://github.com/gohugoio/hugoDocs/issues/389, ..), and in light of https://www.youtube.com/watch?v=qC1OYK5oqDo may be we can facilitate people's involvement (and at least me) in the documentation.

Steps could be :

1. Define main organization and structure
2. Define some "important" items in how-to, tutorial for a start
3. Define some guidelines about having some consistency. Could imply to write some shorcodes/layouts to help people ?
4. Migrate some existing articles/post in those sections.
5. Adapt things depending how this works/helps.

Thoughts ?

[pointyfar]

I suppose a good place to start is the question of direction, which overlaps with 1. 2. and 4. above.

Do we take the 4-part documentation suggestion (ie tutorials, how-to, explanation, reference) as the goal?

If no: what instead?

If yes: would the preference be: to write articles (tutorials/how-tos etc to add to existing docs) fresh? Or link to existing ones?

Related to 4., and with the assumption of the 4-part segmentation as the goal, I've started a spreadsheet.

I copied the existing documentation sections + pages and noted where these might fall under the four main divisions. It needs more work of course, but I thought I'd get the discussion started.

I'm happy to continue to work on this unless I am wildly off-mark with what the rest of the contributors/community/gang thinks. Which would then bring us back to the question of direction.

Also: Would it be better to discuss this in the forums? We might have more eyeballs there, which is both good and bad.

[divinerites]

Cool. I'm in the same mood as you.

would the preference be: to write articles (tutorials/how-tos etc to add to existing docs) fresh? Or link to existing ones?

I personally prefer to start fresh, to help consistency and coherence, even if it will be more work. And we can also have a sort of footnote/info box with a link to the original article + citation. But we can't rely on availability of someone else's blog. And the user experience will be 100x time better if all is on one site.

This also lead to having the green light from authors to "sort of rewrite" their articles, and copy them in the doc if they do not want to do it themselves.

Will look at the spreadsheet. And I agree that we only should start if this way of seing doc evolution is in phase with what bep's and al. are ok with. It is out of question to force/go against the way they think is good for the doc.

Re forum vs issue, I think forum in this situation leads to unefficient bla bla frompeople who do not want to really be involved. So may be start and define the rough aspects here and then later, discuss the details on the forum ??

[bep]

Whatever we do, I suggest that we start with totally blank sheets, and a way to do that would be to just move all the old stuff one level down (or something). Then we could do something ala: "This section currently is on the short side; you may find more useful info in the old docs ..."

I think we also need to start fresh with a new theme as well ...

[ulab]

May I suggest some versioning for the documentation instead of "old" and "new"? You never know if there will be another rehaul in the future.

Then as @bep suggested, I have seen headers like [This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.](https://wiki.dovecot.org/Tools/Doveadm or a version select box like on Gitlab - but that one is not a documentation version, but based on the software.

I'd give bonus points for adding direct links to the corresponding pages (if they exist) in the other version, not just the general documentation toc 😉.

[pointyfar]

I've started working on a revised structure, basically a brain dump of "all the things that need documenting in Hugo". It is neither complete nor exhaustive, but it's a start.

Running with the four main segments:

• Getting Started With Hugo explains general and basic concepts
• How To Do Things With Hugo these are the "how-to" articles, divided into main topics
• Technical Reference variables, functions, config options, etc
• Tutorials longer articles

The draft structure is in this repo: https://github.com/pointyfar/hugo-docs-revamp-proposal

The demo (using the Learn theme currently) is here: https://sleepy-noether-c999b7.netlify.app/

Let me know any thoughts / comments / suggestions.

[tgarlot]

Few comments on the structure:

• I would keep an About Hugo as this is "expected" and quite cool to get to know Hugo. Compared to today, just keep "What is Hugo", "Hugo Features", "Licence" and "The Benefits of static" (not in this order)
• Then clearly a Getting Started as proposed above. Should be straight to the point as most users will directly head to it. The current "Quickstart" is fairly good so should be at the top of this section. Then agree with @pointyfar : should cover the "common concepts" and the "site structure". Less convinced about "Templating" as this start to be a more "advanced" concept and is probably better in How to's
• Then REALLY like the How To's structure. Does not have to be so structured but the main sections should be crystal clear. Important: the How To's should point extensively to the Reference pages ("See also")
• I would add a Contribute to Hugo or similar top section to explain how to participate in Hugo or Hugo Docs.

Really great work for the new structure, was expecting this each time I'm on Hugo docs site :-) Even if the content is here, not always easy to know where to find it.

[divinerites]

The draft structure is in this repo

Great. Thanks. And it is a smart way to have the whole structure in a single file. Will be helpful for collab on the whole structure.

So how do you see thing ? Do we propose some PR on your repo for updating content and order of items ? Do we keep the structure talk here ? Or move the talk on your repo ? (not sure about having a third place to talk).

[pointyfar]

Do we keep the structure talk here ? Or move the talk on your repo ? (not sure about having a third place to talk).

Good points. It's probably better to keep the majority of discussions here, so it's "official". I'm happy to either take comments / suggestions here or PRs on my repo.

---

I am by no means saying "my proposal is the way to go" at this point. My aim is mostly around getting "which direction are we going" and having my proposal as a basis for discussion.

[tgarlot]

Really like the approach (PR in @pointyfar repo, comments/dicsussions here). With the comment above from @bep , I assume this is a "green light" to start :-).

[acanalis]

The ideas here are all very valid and would very likely improve the docs.

Setting that aside;

• The particular details about why the current docs are not good enough haven't been discussed, and there's a risk on doing the same thing twice.
• There are only 10 of us here now, when in the original forum topic there where 43 answers. The forum is where "the people is at", and it would be nice to find ways so that everyone could chime in, not just us.

How about doing a survey to identify the places where the current docs have failed, so that we can design the next best thing?