search

google / docsy

A set of Hugo doc templates for launching open source content.
https://docsy.dev
Apache License 2.0
2.61k stars 901 forks source link

README should describe how to build and test docsy, not how to use it #846

Open chalin opened 2 years ago

chalin commented 2 years ago

The target audience for the README and CONTRIBUTING should be docsy contributors, not end users. The content of these files should describe how to contribute to and maintain (build and (eventually) test) docsy and its user guide.

Docsy endusers should be directed to the user guide.

WDYT @LisaFC @emckean?

LisaFC commented 2 years ago

Hmm, good point - a lot of what's in the README for Docsy users is duplicated in the user guide, though I think it's lightweight/short enough that we can leave it there for people who find the theme first in GitHub. It at least gives end-users a quick idea of what's involved in basic theme usage (and that we have an example project) and whether it's a good choice for them before they go off to the proper docs.

I would suggest maybe adding an extra section for contributors describing how to build and test. Can also point to this page (which could probably do with a refresh): https://www.docsy.dev/docs/contribution-guidelines/

Erin, what do you think?

chalin commented 2 years ago

Users will soon have a couple more options when it comes to using Docsy. I'd vote to keep things DRY and only document usage scenarios (and migration instructions!) in the UG.

emckean commented 2 years ago

Hmmm ... a lot of our links right now link to this repo, but the links are geared towards users, not contributors. What about keeping the Prereqs, then merging Example/Usage/Documentation into a How To Use and/or Quick Start (which would be useful for contributors as well) and then a strong push towards the expanded documentation?

Then the rest of the README can be contributor-focused. Thoughts?