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.
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.
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).
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.
