search

rdwatters / hugo-docs-concept

NO LONGER MAINTAINED. See the official Hugo docs at /gohugoio/hugoDocs
17 stars 10 forks source link

Improve Troubleshooting docs #30

Open ghost opened 7 years ago

ghost commented 7 years ago

After running into 2 different errors today, I was thinking about improving the Troubleshooting documentation.

  1. Git submodules. Installing a theme with git clone is all well and good, but it should also be added as a submodule.

  2. Netlify doesn't always have the most recent Hugo version set as their default version. Currently it is set at 0.17. Netlify allows people to specify more recent versions.

I searched the docs, and I only found a throwaway line about submodules on the Hosting on GitHub tutorial. This seems like the sort of thing that should be explicit in multiple locations: Installing & Using Themes, Relevant Hosting Tutorials, and a Common Errors page. Does that sound reasonable?

If Netlify says it is using the wrong version of Hugo, does it make sense to include that with other common Hugo errors? Or should it just stay in an error section in the Netlify tutorial?

I'll submit a PR updating the docs regarding these errors.

rdwatters commented 7 years ago

Or should it just stay in an error section in the Netlify tutorial?

I'd keep it in the Netlify tutorial. Call out "gotchas" as either "warning" or "note" admonitions, depending on the severity of the consequences.

I think the goal moving forward should be making the line clear between what is Hugo and what isn't Hugo in the docs. I like the idea of discussing submodules---and you're right that's the only way to run themes with Netlify--but I think it should be part of the Netlify hosting doc exclusively. Getting into walkthroughs of how to use Git has a very slippery slope, and besides, it's unlikely that end users are going to come to gohugo.io for this type of information, at least at first...

ghost commented 7 years ago

That makes sense.

Re: Hugo errors, what should be the criteria for including them in the Troubleshooting section? There is already the issue tracker, so presumably the Troubleshooting section should be far more limited in scope.

rdwatters commented 7 years ago

presumably the Troubleshooting section should be far more limited in scope

Agreed. What's there right now has largely been obviated by improvements in Hugo over the last 5 releases. This is going to be a largely qualitative decision based on forum community feedback... That said:

https://github.com/rdwatters/hugo-docs-concept/issues/20

There is also the template debugging page, which I'm wondering whether that should belong under "templating" or "troubleshooting" or....both? I have to stew on this a bit...