-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Define an upgraded structure and sections for improving tutorial & how-to docs #1289
Comments
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: If yes: 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. |
Cool. I'm in the same mood as you.
I personally prefer to start fresh, to help consistency and coherence, even if it will be more work. 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. Re forum vs issue, I think forum in this situation leads to unefficient bla bla frompeople who do not want to really be involved. |
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 ... |
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 😉. |
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:
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. |
Few comments on the structure:
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. |
Great. Thanks. So how do you see thing ? |
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. |
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 :-). |
The ideas here are all very valid and would very likely improve the docs. Setting that aside;
How about doing a survey to identify the places where the current docs have failed, so that we can design the next best thing? |
Following https://discourse.gohugo.io/t/has-hugo-become-too-complex/29609/41 and other threads (#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 :
how-to
,tutorial
for a startThoughts ?
The text was updated successfully, but these errors were encountered: