This is not a theme; this is a complete overhaul of the Hugo docs, particularly the content component.
I am looking for feedback on content and not design. The awesome @budparr has already volunteered to help clean up the homepage (it needs some love).
Please respond to content-related feedback on this thread or submit via GH issue.
Everything that is a WIP is marked as such on the published page, but I’m still open to substantive feedback on how the content in those pages can be improved.
As an Irish-American, I will be out all day today celebrating an early St. Patty’s. My earliest responses will be tomorrow afternoon (Sunday, CST).
The Ask of the Hugo Community
What was the most difficult concept to grok when you first started learning Hugo?
Gotchas? Logical inconsistencies?
What are the greatest strengths and weaknesses in the current documentation?
What’s hard to find? Which parts seem contradictory? Any outdated material?
W/r/t sections or general areas of this new concept site, do you see any large content gaps?
When approaching Hugo for the first time, what should the assumptions be about the end user’s skill set, knowledge level, etc?
All other content-focused feedback is welcome.
Note: All of this will need the blessing and input of @spf13 before it goes anywhere. I would love for the new documentation to ship with v20 and be moved into the Hugo repository.
Select Highlights
Just a few of the improvements that are currently springing to mind:
Search is exponentially better
“Extras,” currently the largest content section on the site, has been completely removed and incorporated into multiple other areas.
Semantics are improved across the board…way too much to detail here, but just think “definition list”
SEO: twitter, OGP, schema.org, shareable default image, and many others…
Mobile-first: the site’s menu, at least from testing thus far, is much easier to access on smart phones and tablets. If you see a major usability bug here, please submit an issue.
Content pages are crazy fast. We will inevitably get dinged once I add the GitHub buttons and Google Analytics.
Please clarify. The mouse is not actually disabled but rather hidden via pseudo-selector. I take 508/accessibility seriously, so I certainly appreciate the feedback!
Need page under Troubleshooting that discusses build performance issues. Lots of forums threads that give the same answers. Should call attention to --verbose, --stepAnalysis, and --renderToMemory (for troubleshooting disk I/O). Highlight partialCached template function.
As a link within the body copy or are you saying that the menu link should take them directly to GH? The latter is easier to maintain for obvious reasons.
Added. Just placeholder for now; I will try and write something out as I continue to iterate through the copy.
partialCached will definitely be highlighted. It also has it’s own function page and is highlighted as a section within the partial documentation. Comes up really well in search too
I’m impressed with the new site and efforts of @rdwatters. I know first hand the complexities of writing technical documentation, but it seems to flow easily here.
By the way, do you plan to take some time off @rdwatters after completing the first draft of the documentation? I’m asking because you make us look bad for not doing more.
Do you think it would be worth rethinking the details related to the folder structure and what will be rendered? For example there are many pages that speak about it and there is a need to find the specific pages for each sometimes. I know I saw a lot of conversation on this in the discussions when I was looking recently. Would it be better to combine most or all of the details related to this to one page with links to more details if needed? Are blocks the preferred use case now? If so should it be centered around using them? I clicked around a bit and came up with this list of pages that talk about it ( I could have missed some ):
with the listing on the side? Maybe a bit more static in the way it scrolls. Its definitely helpful to have the list you have done on the example. Thoughts on this?
Not now that I’ve moved all the functions to individual files.
That said, single-scrolling is less SEO/Google friendly, but really this is now a question of layout vs content, which are effectively separate concerns on the new site.
I have considered having the secondary “kebab” navigation (just for functions) switched to a functions listing to indicate where the user is within the shorter list of quick reference titles…
If you’re talking about grouping and namespacing functions, I would look into the conversation here:
This is more a matter of figuring out the right attributes (front matter) for the function content type,which will likely happen when/if the above dev-related conversation is resolved. It’s also a question of where to draw the line between beginner-user-friendly documentation and API documentation and good-old-fashioned “how much do we want to show what’s really in the sausage?”
Nevertheless, there is definitely conversation going on in this arena, and I appreciate your input
@shawn Again, I’m loving the feedback, but the request was to review the concept site and not the existing site. FWIW, I agree with you that blocks needs to be placed in a better position. Please take a look at the https://hugodocs.info/about and let me know what you think
Thanks, @Jura That’s a really nice thing to say because I’ve had fun working on this. But at the end of the day, it’s just the documentation for the project that I’ve worked on. The actual devs deserve all the credit.
Otherwise, it’s like congratulating the guy who wrote the Ferrari owner’s manual
Please keep the suggestions coming. I appreciate the feedback!
