Documentation restructure and -design


#1

The graphics above shows the concept of the “long tail” – or the distribution between what is popular (say 20%) and the rest (80%).

I would say that in the current documentation, the head and the tail is well mixed together. Ryan Air is used as a quality example in this discussion - the web page is ugly as hell, but booking a flight is right in your face (figuring how to complain for lousy service is almost impossible to find).

Some nerds say that the Hugo doc is great. But it has been added on over time and is now a patchwork.

Starting fresh would be good, me think; and with a strict focus on what 80% of the users want to know:

  1. How to create a site
  2. How to use a theme
  3. How the hell does this crazy layout template logic work

The above may be wrong, but I believe we need a more focused documentation.


#2

Really interesting post. And applicable also to tne current blog / marketing discussion. Apologies in advance for focusiing on marketing as well as documentation, but it seems relevant to this and other discussion.

That’'s a great perspective in my opinion on how it can be improved.

[quote=“bep, post:1, topic:1891”]
Ryan Air is used as a quality example in this discussion - the web page is ugly as hell, but booking a flight is right in your face (figuring how to complain for lousy service is almost impossible to find).[/quote]

In my opinion there is a lot more to that ‘ugly’ site than is first apparent. I would say it was very carefully designed to look how it did. For a very specific reason - to emphasise ‘cheap’.

A demonstration of excellent marketing by Ryan Air. The first impression they gave? Ugly and cheap. But in that marketplace with those competitors, it worked really well (to show that with some other airlines you were paying for ‘posh’). Now more extablished and looking at atlantic routes, the website is less ugly. I think it was all intentional.

Not wrong in my opinion. I think you have outlined a very good approach to new documentation. For me it really takes into account this impression users quickly form about a project, one that makes the decision if they stay and persevere or not.


#3

I’m happy to pitch in as I use Hugo and I haven’t learned Go to contribute elsewhere. Do you have a strategy in mind, @bep ?


#4

The timing of my post wasn’t random.

Help is needed. I wouldn’t be able to build this alone if I tried (or, I would, but it would be slightly ugly).

Strategy? I just came up with this idea … My normal strategy would be that of brute force, but in this case I believe we should think a little first.

I have moderated this thread’s title: It’s more about restructuring/design than rewriting. People should still be able to read about the inner workings of shortcodes, but it shouldn’t be the first they see. Today everything has just about the same weight.

If we add installation to my list of important items, I envision this:

  • A clean doc landing page with no menu
  • Bottom right corner:
    • A simple/advanced toggle button toggles between the two simple/advanced modes of the doc (the advanced would then more or less reveal all the current content … maybe)
    • OS selector (try to detect it)
    • If advanced mode: Also show “preferred front matter format” (TOML, YAML, JSON) (for the samples) (defaults to TOML)
  • Store these settings in a cookie
  • The main part of the page: Maybe a wizard style navigation with 4 slides:
    • Short and bullet proof Installation guide for the selected OS (a one click installer would be cool; there are currently like 4 ways to install Hugo on OSX …)
    • Short and bullet proof guide on how to create a new site (maybe add some related tips in the corner with consistent formatting; “Have a Jekyll site you want to convert? Click here”)
    • Short and bullet proof guide on how to select and use a theme
    • Short and bullet proof guide on “how to add my own content and adapt the layout”

So my strategy would then be:

  1. Figure out if this is something we want to do
  2. Agree about the basic ideas/shapes of the site
  3. Get someone to create a prototype design of that main page.
  4. Do the work.

#5

I agree with @bep. Initial goal was just to have documentation and capture as much as we could. Just doing that puts Hugo ahead of most projects. The next step is to craft a better on boarding experience. I think we definitely need to treat some content on a different level from others. I think we need to have an on boarding experience first and the complete docs as second.

Today Hugo is a splash style homepage and the docs. Perhaps we need more than just a homepage, but a more complete site and link to the “Docs”. Not sure all that the site would entail, but I do think it’s more than just documentation.


#6

I think part of this could be handled by godoc (and some reworking of the code to make it godoc-friendly). it’d be great for users and (potential) developers if

  • every user-facing part of hugo has docs in the source; right now, for instance, there a bunch of the template functions don’t have docs, and the exported functions on that page don’t give the template name (its key in funcMap), nor do they provide a comprehensive list of the available functions.
  • there were links from a more beginner/tutorial site to the godoc — “for more information on the available template functions, see [here].”

Still going along with the template example, this page would be made obsolete by switching the “reference” documentation over to godoc.

tl;dr: have two different sites for documentation

  • one more geared toward beginners, being more tutorial based — answers “what can Hugo do?” and “How do I do this?”
  • one for more experienced users; a complete reference — answers “I know what I want to do, but which order are the parameters in?”

#7

@bep I like your approach of guiding the user automatically to the right spots. It sounds more or less like a redesign of the docs. How do you want to realize the dynamic parts? Should we make them static (which means to generate mulitple sites) or should we build something like a Javascript application to make the docs dynamic?


#8

In my head, a little bit of both, but I haven’t thought hard about this.


#9

This might be something I can offer input on.

I currently run the website/support forum for an open source tool called ‘get_iplayer’, a free, open-source third party tool for accessing BBC iPlayer content. Hugo powers the site and MyBB the forum. You can see it here:

https://squarepenguin.co.uk

I faced similar challenges to what you are facing here and had to iterate the design to come up with something effective. The most important thing I learned was providing easy ‘self-segregation’ to users so they could select their ‘path’ through the site instantly.

For example Downloads, Wiki, Guides, FAQ and Support are all top nav options. Users generally flow from the landing page to the Downloads section and then to guides - those are the ‘popular’ end of the tail. The long tail end comes with the Wiki and the Support Forum.

My sites on-boarding experience is basic to say the least, but seems effective with around 17,000 uniques a month and (I think) around 2000+ installs a week, but I don’t have direct metrics on that yet.

Given the ‘command line’ nature of both tools and probably a similar split of experienced/beginner users I think that the suggestion to have a more ‘complete’ Hugo site with an on-boarding experience sitting alongside docs is a good way to go. At the moment, Hugo’s docs are quite Wiki heavy and teasing out the tutorials from the wiki stuff and adding in a more streamlined download/guide flow would be a good improvement.


#10

I’d be super happy to contribute to the writing, editing and rewriting of docs. I’m new to Hugo, but I love documentation.

In my experience so far (reasonably valid as a new user), the documentation appears to be grouped for internal developers, or seasoned users. So, if I want to learn all about Taxonomies, I can. But there’s no easy way to understand how Taxonomies fit into the overall development experience. I feel almost immediately lost as there’s no 10,000ft view of the project.

I think the AngularJS docs could serve as an excellent reference point. They do a great job of separating the introductory / conceptual stuff from the technical breakdown. The best page by far is Developer Guide > Conceptual Overview. It dedicates a few lines to each component and offers links to the API reference.

Regarding the current Hugo docs, this is my experience thus far:

About Hugo

  • There’s nothing here actually about Hugo. It’s the release notes, roadmap and licence. That was my first huh? moment and it happened immediately.

Getting Started

  • Introduction - A complex mix of things: What is a Static Site Generator? How Fast is Hugo? A little about the Concepts (with no intro to the terminology). Feature List. History of Hugo.
  • Quickstart - good, no need to talk so much about installation - just the link. Otherwise good.
  • Installing Hugo - fine, but should be first. Certainly not after Quickstart.
  • Using Hugo - should be renamed to Command Line Usage. Remove the deployment stuff into another page (but crosslink it here).
  • Configuring - good, rename to Config Files.

Content, Themes, Templates, Taxonomies and Extras

I’ve not read through all of these yet, but this is probably the most troublesome part. My gut feeling is that I’ll need to flip-flip between the intros for each section in order to understand how they all fit together. I’m not looking forward to the experience, but am excited to reach the aha moment at the end.

What I think is lacking / missing

  • A page about nomenclature. The intro pages, quickstart etc. use Hugo terms straight away, and it’s confusing. Organization… do you mean a group of people, or how I keep my files in order? Or organise my Posts? What’s a Section? A Section could be anything, it’s like “thingy”. And in HTML terms a <section> is well defined. Taxonomies? A grouping of Sections I assume? Or maybe a group of Content… Wait up, are Taxonomies and Organisation the same thing? And so it goes on.

I hate to hark about the AngularJS Docs, but this table is fabulous to see early on (below) - the descriptions are amazingly naive but seeing it all together really helps paint a picture of the whole system. The order appears to reflect the order that a new user would learn AngularJS. Yes, I absolutely need to know about Data Binding, but not until I’ve seen it used in Templates , Models and Scope… you get the picture.

  • There’s a lot of missing indexes. I really want to see a list of pages and a line about what they contain. As it stands I have to pick (almost at random) and hope it gives me something I want. The Extras section is a great example - I see “Scratch” but until I skim the page I have no idea what it is.

  • Crosslinking. Lots of opportunities to read more. on each page, that are sadly missing. Take a look at the Quickstart page for a good example, if I want to read more about templates I have to hope to find the right page via search or the menu - which has an uncomfortable air of luck.

I’ve always like the way Amazon says “people who viewed this item went on to buy…” - is there an opportunity to do something similar with each page? So after reading “Installing Hugo” I probably want to be prompted on to quickstart rather than to the the contribution guide (which should be a page in it’s own right).

  • Those Previous / Next buttons - they’re pretty, but useless due to the unusual grouping of content and the lack of titles. See Mystery Meat Navigation.

Overall Verdict

Seemingly awesome software, documentation is good, but difficult to navigate. Particularly tough to get an overview.

In a strangely ironic turn, I think I need to learn more about Hugo before I can properly contribute to the documenation - I made one simple Pull Request for the docs but the difficulties I’m having in using Hugo have stopped me from doing more.


#11

Tutorials, Courses, Articles and Videos

It would be great to see links to 3rd-party content that has been vetted by the community. Interesting posts, articles, videos etc. A must would be to have them: dated, Hugo version number (if possible), a brief synopsis and finally anything of note. ie:

Hugo Quickstart
Feb 2016 - v0.15


Shekhar Gulati gives a quick walkthrough of how to create a “boookshelf” website, covering: installation, adding content, downloading templates, modifying templates.
Notes - hugo_theme_robust has no closing </body> tag, this causes issues with LiveReload.


Code Examples based on a Seed Project

A seed project could provide an excellent starting point for code examples. Because of the scope of Hugo, snippets of code can be difficult to understand without context. By using a Seed Project as a reference point, those snippets could be put into context.

Looking at Content List Template #examples, it’s tough to figure out the difference between section templates and list templates. The description is identical and the code is very similar. (I still don’t understand the importance of these examples).

Using a Seed Project, the language becomes more accessible, ie:

On our Seed Project you will see two similar templates path/to/list.html and path/to/section.html. The difference between these pages is subtle, but important…


Content List Template

While I’m looking at it, this page should probably be split into two - one to explain list templates, then another to cover tag {{ tag }} documentation (ordering, grouping, filtering)


#12

Hugo Commands

Could benefit from showing the header line alongside each command to save skipping back and forth, ie:

  • hugo
  • hugo benchmark
  • hugo check

becomes

  • hugo - hugo builds your site
  • hugo benchmark - Benchmark hugo by building a site a number of times.
  • hugo check - Check content in the source directory

(in tabular form)

Refine this Page

Is out of context - this should be at the bottom of the main article rather than in the menu.