Quick start doc feels like it could be improved

brianly · 2018-12-30 19:26:51 UTC

Let me start by saying I feel a little bit uncomfortable about posting this because folks seem to be very proud of the documentation available given the “How to Request Help” announcement that I got when I signed into this forum. My intention is to try to suggest improvements for folks who are trying to get up to speed quickly and like to learn by poking initially, before spending a lot of time on the docs.

I have a site (mostly blog, partly static pages and photography) which I moved from WordPress to a Python-based static generator (Acrylamid) which has been discontinued. After moving to a new computer I was frustrated at the setup because I was never able to get it working easily on Windows. I spend time on Windows, Mac, and occasionally Linux, and want to be able to publish from any of them. Hugo seems to fit the bill with the platform support and is unlikely to be discontinued in the short/medium term, so I have to decided to move to it.

I went straight to the Quick Start as my starting point because I’ve worked with these kind of tools before. I copied over my existing content in markdown format, and lo and behold it just published. To be more accurate it was published, but my post list and recent posts didn’t display - just the couple of posts in the /posts directory.

My problem, and the thing that I want to point out, is that I felt that I was left a little high and dry. The remainder of the Getting Started section at the time of writing reads like separate articles for the most part, so the Quick Start doesn’t lead you towards a progressive understanding of Hugo.

If someone is looking at this area of the docs it would be great if:

A simpler theme than ananke was used. Ideally, it would be built around learning the product as much as being theme someone could run on their site. It took me longer than expected to reverse engineer what was going on so that I could do my copy and paste of HTML from my old Jinja2 templates.
The quick start continued by doing a tour of the theme with suggested modifications that added some common features.
Template language and look up rules were highlighted in the context of the quick start example.
More examples of how image and video content should be added to a site is presented.

This might seem like a lot to include in a quick start, but I think that it can be covered fairly tersely and provide a much better experience for the more experienced developer with zero Go Templates or Hugo experience.

Thanks for reading!

-Brian

maiki · 2018-12-31 03:58:00 UTC

I don’t think that is the case. The alternative is to not link to the documentation. Regardless of the quality or relevance, we have to point to the docs if we have them, ne?

The only thing keeping the quick start doc from being updated is someone has to do it. You can do it, if you want. I’ve made lots of changes to the docs, it is fairly straightforward.

bep · 2018-12-31 10:27:21 UTC

I wrote the current Quick Start. It replaced an older 500 step “quick start” that only worked if you broke a wish bone while doing it. We have had so many posts here on the forum thats says “the quick start failed at step 321” to demonstrate the value of something short and to the point.

So, while I do think It has room for improvement, I’m not sure “adding more to it” is the answer. You need to read further after doing the quick start.

That said, I think the current quick start does not bring you close enough to something useful. I think there are themes that would fit this bill better (maybe using Hugo Pipes, SASS etc. to make it easier to tweak the look and feel).

brianly · 2019-01-01 01:22:44 UTC

I can see where you are coming from. I’m not at the point where I think I can write a version that fits with what the community considers best practice, but I’ll come back to this when I’ve got some more experience with Hugo.

zwbetz · 2019-01-01 02:12:35 UTC

While a tad aged, the “Creating a new theme” post from the Hugo basic example site is a good long-form intro into templates, among other things.

github.com

gohugoio/hugoBasicExample/blob/master/content/post/creating-a-new-theme.md

---
author: "Michael Henderson"
date: 2014-09-28
linktitle: Creating a New Theme
menu:
  main:
    parent: tutorials
next: /tutorials/github-pages-blog
prev: /tutorials/automated-deployments
title: Creating a New Theme
weight: 10
---


## Introduction

This tutorial will show you how to create a simple theme in Hugo. I assume that you are familiar with HTML, the bash command line, and that you are comfortable using Markdown to format content. I'll explain how Hugo uses templates and how you can organize your templates to create a theme. I won't cover using CSS to style your theme.

We'll start with creating a new site with a very basic template. Then we'll add in a few pages and posts. With small variations on that, you will be able to create many different types of web sites.

This file has been truncated. show original

mojoa · 2019-01-01 02:35:10 UTC

I appreciate your hesitation in creating documentation when you feel you need more experience.

It is not a great idea to have the student pilot write the training manual, although the feedback is invaluable!