This keep is built utilizing the Hugo static keep generator. Hugo is pleasurable. Its documentation is just not any longer. That is my non-public thought 🙂 This submit explains why I safe the present documentation so frustrating and the arrangement it would also very properly be improved.

Context and background

First issues first: Hugo does indulge in a ton of precious documentation. I’m tickled it exists. *Insert first-rate statements right here about how Hugo is an originate offer conducting.. we needs to be grateful that the scientific doctors even exist.. that users might perhaps perhaps perchance restful step up and make contributions to bettering the scientific doctors.. etc. Right here’s a properly-intentioned critique for bettering the advantageous of the present documentation.

Secondly: It’s a ways capability that the bulk Hugo users are arrangement more an expert, or patient, than I’m and ensuing from this truth indulge in no longer faced any of the considerations described below. Web construction is just not any longer my strong point. I on occasion dabble with it as a hobby, as an instance when making a suite corresponding to this one. Within the previous, I in actuality indulge in self-hosted and feeble Joomla, Drupal, Wordpress, Octopress, Pelican, and Grav. Never the rest in particular admire though and I’m no longer an expert. With that out of the arrangement, let’s dive in and pain at two problematic patterns.

Problematic patterns

Pattern 1: Studying a page of Hugo documentation from top-to-bottom for the principle time hardly helps me impress a belief or earn specific answers. More in most cases, as soon as I open reading something, it turns into well-known to department off and first be taught about a definite-however-linked belief. Recursively. Open reading page A and after barely a paragraph, it’s well-known to jump to page B. As soon as on page B, must jump to page C virtually straight away. And so on. Soon, I’d be on page Q, whereas attempting to support the total partly be taught states of pages A via P in my head and attempting to admire something on page Q without forgetting my fresh pursuit. Worse, the principle paragraphs of some page M would account for page N, whose first paragraphs in turn would point abet to page M ensuing in a spherical dependency. The pause consequence’s that I’d must be taught a whole bunch of pages whereas barely notion the rest for the length of the principle reading and with the preference of unresolved questions consistently increasing in my thoughts. Easiest after reading a host of pages and ruminating over them concurrently would the bellow of any one page open making sense.

Pattern 2: Inside of a documentation page, fresh ideas or terms are as soon as in some time offered without clearly pointing out what they are or how they present to more than seemingly the most trendy topic. This makes it seem just like the documentation has switched to a pair arbitrarily totally different topic. In spite of every thing, that is just not any longer in actuality the case. It’s a ways ethical that the the fresh topic and its reference to the previous topic isn’t explicitly offered.

A concrete example

Let’s see at a concrete example of every these patterns within the documentation page describing Order material Organization. Right here’s a conventional page that a whole Hugo beginner would must be taught. (For the rationale that bellow of this page might perhaps perhaps perchance evolve in future, this PDF is a static snapshot of what the page feels like on the time of penning this submit.). Let’s be charitable and fake that the reader is a conscentious particular person and has landed on this page after no longer no longer up to skimming the Getting Started allotment of the documentation. The see as you open reading the page is proven below.

On the locations of the numbered red circles, my thoughts are

1. “..page-relative photography and other sources packaged into Page Bundles.” K, however what is a Page Bundle?
2. “These terms are connected…” Which terms??
3. “..to earn the beefy picture.” Fleshy picture of what? Presumably of Page Bundles? K, I could perhaps perhaps perchance want to be taught these two hyperlinks (Page Resources and Image Processing) to totally impress this.
4. “..Display camouflage that the dwelling page bundle..” What “dwelling page bundle”? Which without a doubt one of many three red containers within the image is the dwelling page bundle? The note ‘dwelling’ does no longer seem wherever within the image.

Display camouflage that at this point the reader restful has no belief what a “Page Bundle” is, rather than it is which programs page-relative photography and other sources. Having a peep on the screenshot, it’d more than seemingly circuitously be inferred that a Page Bundle is a folder/list that has some bellow? However that is just not any longer explicitly talked about wherever. K, let’s discontinuance reading this page and gallop click on on these two hyperlinks. The image below reveals what happens whereas you pause that.

• The Page Resources page states that “Page sources are easiest accessible from page bundles, these directories with index.md or _index.md recordsdata at their root.” Obliging! So the hypothesis that a Page Bundle is a fresh list with some special bellow looks to be appropriate. BUT.. to the truth is know what a Page Bundle is, you now must jump to the linked page about Page Bundles.
• The Page Bundles page begins off by telling you that, “Page Bundles are a technique to crew Page Resources.” So hello, that’s a link abet to the page we came from. At this point, we restful don’t in actuality impress what a Page Bundle is.. nor indulge in we but understood what Page Resources are. So more than seemingly be taught this page, the previous page on Page Resources, and the fresh page we started from, to admire every thing? However wait, now we indulge in no longer but visited the Image Processing, which is one more unknown belief. Let’s pause that first.
• Focus on over with the Image Processing page. Literally the principle line hyperlinks to the Page Helpful resource page and the second line hyperlinks to the Page Bundle page.

At this point, as a reader I in actuality indulge in visited 4 pages that consult with one but some other. I started by no longer vivid what a Page Bundle is and I restful earn no longer fully know that. Furthermore, I earn no longer know what Page Resources are and what Image Processing is. I indulge in to be taught ALL these pages.. pray they earn no longer lead off to other pages (spoiler: they pause!) after which ruminate over every thing I in actuality indulge in be taught for it all to ‘click on’ collectively in my head.

Display camouflage that dense interlinking of field material is in actuality loyal. The truth that these pages all link to one but some other is loyal! The lisp is that the pages form no strive to be even partly self-contained with hyperlinks pointing to elective extra/in-depth field material the reader might perhaps perhaps perchance want to be taught. Comparatively, pursuing these hyperlinks is in actuality well-known to even open notion what the page is set. The closest programming analogy I can deem is a nested chain of capabilities: Characteristic A calls Characteristic B which calls Characteristic C etc. and this system drift needs to stream down that feature chain after which abet up before the fresh Characteristic A finishes execution. Similarly, with Hugo scientific doctors, within the occasion you open on Page A, you will want to stream to Page B, which then forces you to Page C etc. and likewise you will want to be taught all of them (with some spherical hyperlinks amongst the pages) after which abet-pedal the total arrangement to Page A in dispute to admire what Page A is set. Right here’s an exemplary occasion of Pattern 1.

Display camouflage: The Order material Organization page does affirm that “The bundle documentation is a work in growth…” The element is, the Page Bundle documentation exists.. it’s ethical no longer referenced within the allotment on Page Bundles. However let’s proceed reading.

• “Whereas Hugo helps bellow nested at any level, … .To be taught more about sections,..” Huh? What the heck is a “allotment”? How is a “allotment” linked to what’s being described? This page has actually by no arrangement talked about the note “allotment” so a ways and all of sudden, reputedly and not utilizing a reasoning, it is asking the reader to stream to one other page to be taught more about sections. Right here’s an exemplary occasion of Pattern 2. Ride, I’d merely click on the link and discover, however that’s going to be one other rabbit hole. Let’s ignore this and proceed reading the page.

The documentation page now begins talking about a file named _index.md which has no longer been offered before. The description of _index.md is that it “..has a definite position in Hugo. It helps you to be succesful of add frontmatter and bellow to your checklist templates. These templates comprise these for allotment templates, taxonomy templates, taxonomy terms templates, and your homepage template.” Argh! At this point, to admire what _index.md is in actuality precious for, more than seemingly you will want to admire what a checklist template is and more than seemingly even what ‘allotment’, ‘taxonomy’, ‘taxonomy terms’ and ‘homepage’ templates are. The documentation has basically asked the user to be taught up on five fresh terms in dispute to admire what _index.md is precious for.

Must you were following along so a ways, at this point you are about midway via the documentation page without having understood mighty of the rest! Your knowledge of your lack of consciousness has elevated, nonetheless. You now know that you are going to pray to be taught loads more before stuff begins making sense.

increase?

1. Pattern 1: It’s now not any longer feasible, nor recommended, to form every page perfectly self-contained. Alternatively, if Page A mentions a theory that is described in-depth on Page B, it helps immensely if Page A temporarily describes the belief so that the reader can take care of a ways from jumping to Page B. The reader can therefore gallop to Page B for better notion, however needn’t fracture immersion in Page A’s bellow. The Hugo scientific doctors in actuality pause this in some areas, however no longer uniformly or consistently. As an instance, the Page Resources page temporarily describes what page bundles are (“..these directories with index.md or _index.md recordsdata at their root.”). These 10 phrases are more than seemingly ample at that time.
2. Pattern 2: Right here’s an especially egregious error and there might perhaps be rarely a excuse for indulging in it. Correct pause.no longer. open utilizing fresh terms/ideas arbitrarily interior a paragraph without introducing them first. Failing that, no longer no longer up to indulge in a ‘Prerequisite Studying’ Allotment upfront.
3. Calibrate to your readers: In customary, Hugo’s documentation looks to be written by expert and skilled programmers for expert and skilled users. Must you already know a swathe of underlying ideas, then the documentation serves as an first-rate reference. I don’t know if the authors intended for it to be this vogue though. Comparatively that it is uncomplicated for expert other folks to omit what it feels want to be a beginner and that is mirrored of their writing. It takes deliberate effort to be taught what you’ve written with the eyes of a beginner.
4. Many projects structure their documentation into ‘Getting Started’, ‘User info’, and ‘Reference’ with every being gentler than the subsequent one. Presumably Hugo might perhaps perhaps perchance undertake a the same mannequin. Getting Started already exists.
   • There are varied first-rate blog posts documenting varied parts of Hugo and its quirks. May well more than seemingly more than seemingly perchance or no longer it is that the authors passionate ample to write and share these posts would encourage with Hugo’s documentation e.g. sections/chapters in a User Handbook, if the barriers for doing so are sufficiently low?

In a sense, every patterns are violations of 1 and the identical precept of loyal technical writing: Given knowledge comes before fresh. This precept is described and illustrated in this one page PDF file¹. I pronounce that if writers undertake this one precept and no other, it nonetheless outcomes in a spacious magnify in readability (assuming you indulge in loyal bellow to originate with). Through the years, I in actuality indulge in many occasions observed the truth of this pronounce after asking college students and colleagues to follow this one precept.

I in actuality indulge in critiqued the principle half of the Order material Organization page on this submit. The critique wouldn’t be whole if I pause no longer share an example of what the next model of the page might perhaps perhaps perchance see like. Such an example can also also be dispute in right here. By making minor tweaks and adding a couple of explanatory lines, the bellow is arguably more beginner-edifying.

Does any of this matter?

Did I in actuality earn so pissed off after reading Hugo’s documentation that I wished to write a prolonged rant to vent about it? Hmm, this looks to be the case 🙂

The element is, after having spent a host of time tinkering with Hugo, I in actuality indulge in now assimilated ample knowledge that the present Hugo scientific doctors form supreme sense…as a rule. Perchance that is the case with other users of Hugo too.

Alternatively, I restful be acutely conscious how frustrating it felt whereas reading the scientific doctors for the principle time. Each now and then, I’d abandon reading the favorable scientific doctors and peep for a blog submit or tutorial that did the next job of explaining the ideas. Other occasions, I’d re-originate my peep for a Hugo different or ethical turn my abet on Hugo for days on pause till I had the energy for a renewed strive. It felt just like the favorable Hugo scientific doctors had been the final keep I’d restful see at if I wished to search out out how one can whole something with Hugo. It does no longer might perhaps perhaps perchance restful be like that. Hugo is pleasurable. This submit is my small strive to dispute how Hugo can also very properly be made more approachable/edifying for learners.