I have started some work/thoughts about this over here:
The thing is, I rarely use the Hugo Documentation myself …
5 Likes
This brings us back to the “we need people who are not the developer to write the docs” 
And we need some form of calming environment for the developers to answer stupid questions by these people so everything is covered in the end. The docs are not for Bep They are for Sam and Francis who just start out going cold turkey on WordPress.
5 Likes
I think you are one toxic member in these forums you are always sarcastic, discouraging to others specially the beginners when I asked a question in form to find a possibility with Hugo you told me that I am looking for
It turns out what I was thinking that can be done with Hugo actually was possible but you always attempt to shame beginners and discourage them even if you have nothing to contribute to a specific discussion.
and now your remarks here about are not very helpful or supportive to anyone trying to be involved in Hugo as beginner or experts as I see both discussing the same pain point.
So I think more than the documentation Hugo needs a change of mentality. on how it approach and treat users even if someone is go developer he need to learn to use Hugo.
and if people on hackers news discussing it trust me they are not the
thanks
1 Like
I was a little ironic in my remark – while I may not need the documentation, I very much care about the documention and I can identify good documentation when I see it.
5 Likes
I know. Not saying you dislike documentation. What I am trying to say is that the best “explainer” of features is someone, who did not create those features, because creators/developers tend to be blind to details that they think are obvious or that they have been explaining at other documentation locations before. That’s why the “perfect” documentation has how-tos and reference sections for any kind of user.
3 Likes
Hi @bep
I think the existing fonts you have muli is easier to read than the new mulish font.
Also the colour contrast has been lowered which contributes to unpleasant reading. On the current documentation you are using background colour #f9f9f9 and text colour #555 which give color contrast score of 7+ but on this new link you shared the color contrast is only 4.8
I believe the current documentation fonts and colours are better than the new one both for accessibility and for easy reading.
thanks
@pitifi9191 Thanks for that positive critique.
2 Likes
I’m not sure I follow. The dark mode certainly need some adjustments, but the main colors are black (#000) text on white (#fff) background, which should in my head give a pretty good contrast. But what do I know.
I pushed a version using Open Sans as a font, a font I personally really like:
Hi @bep
I compare these links
you can see the one on right isn’t that pleasing to read specially the text under the blue headings.
On this new url you have shared with opensans higher in fonts is a readable font, and very easy to read the documentation comparing to (mulish weight normal 16px).
thanks
Yea, OK, then I understand, those colours come from a scripted conversion from the old source, which I have not manually inspected, so to speak. I was mainly talking about the text in the main articles which should be black on white.
Yes, I agree about Open Sans. I also like the symbolism in its name.
2 Likes
That page has several trackers tha may require GDPR compliance.
Whenever you post something that doesn’t get published in the forum then you should know that you have triggered the forum’s automatic spam filters.
A moderator needs to manually review those posts before they appear.
Therefore there is no need to post the same thing 3 times.
P.S. I haven’t deleted the duplicate posts above, that is for you to do it.
I find the Hugo manual here very cryptic and clustered, with often no information given. An example, Page variables | Hugo
.Aliases
aliases of this page
This doesn’t explains anything at all.
I quite like the PHP Manual Format. Command > Command explained > some examples > user input
IMHO examples are a huge help explaining things.
This said, Hugo is still way way better than some others I checked before coming here.
2 Likes
PHP is 27 years old. They had time to optimise the manual and I am pretty sure they went through all our growing pains too. I remember a PHP documentation that was not too helpful until the comment system was added. Then samples kept rolling in. This too though is connected to a financed backend of people who moderated that. And a continuous “fixing” of methods and principles.
The pain points you hit with the “.Aliases issue” is, that everything that is said at one point in the docs is not repeated where it might be of use. I started doing google searches a la “gohugo.io aliases” long ago when I found something that was not explained enough for me. You will end up this way at the “proper” explanation: URL Management | Hugo - which explains it pretty much.
Too many links though will lead to you overlooking the important ones.
Long story short, there needs to be a way where little parts of the documentation, maybe even just paragraphs or config items can be linked with “related items” documentation about the principles and details, which is better than repeating information (and thus creating multiple locations of content that need to be changed if a function changes).
I don’t know if Hugo has the support of the Algolia team or if it’s using their free features, but the search can be optimised in many places too. I still prefer google to the internal search in the docs.
Typically, design manuals, particularly material design manuals, do not encourage using pure white or black. For the dark theme and typography, I can assist in enhancing the Hugo hues. Should we, however, start a new thread for this?
I look over Hugo’s colors, trying to figure out what’s there and how it’s being used. Hugo colors, I believe, can be used to offer color clues to the content category.
Since you are already using Tailwind css, you can make use of the Tailwind colour palette “neutral” or any other of your choice. This will require minimal code changes for typography.
Here is an example of what I see and a minimal suggestion to enhanced readability:
thanks
Probably. But we don’t start 27 years ago and can look at how it’s done now.
1 Like
Hey ya’ll! So, I’m gonna be upfront, I’m not really looking to discuss the current and past situation, unless it informs our direction. Also, I can only scan HN at best, and please let’s just agree different people and cultures have diverse tolerances for the speech and manners used on HN, and I’m not the audience for that medium.
So… where does that leave us? Has anyone suggested a plan that someone could paste here on how we ought to proceed? Or what expectations are? Because I’m very interested in that. 
3 Likes
2 Likes
I think a first step could be better examples. I don’t mind the documentation that much, except for that. The examples often assume too much knowledge.
I genuinely fear the day my competition starts using Hugo.
Its’ potential being being more publicly available; How do I downvote?