Docs strategy
Opened this issue · 5 comments
gh-pages? docs folder? github wiki? combination of the above?
@LongLiveCHIEF gh-pages site would be cool, although most of the original docs will still apply, and those are just in the README.md 🤔.
Yeah. Thoughts on using README and CONTRIBUTING for docs vs. GitHub pages hosted docs?
I would love to have a searchable doc, which now that I think about it, a README.md file is searchable via cmd+F 🤔.
Fancy gh_pages site could be cool though 🤷♂️
Thoughts on using README and CONTRIBUTING for docs vs. GitHub pages hosted docs?
I don't think it's an either/or with those 3. Imho, all 3 serve a specific purpose, and can be used together to great effect.
I would like to use all 3.
README should be for general overview and getting started, in addition to general status and direction type stuff, guidelines for developing plugins, and simple e2e examples.
CONTRIBUTING should explain our expectations and stack, and describe the general contributing process. It should also help contributors get started and find info on how to collaborate with maintainers.
Pages should contain versioned and detailed/exhaustive documentation, with organization of topics in a way that makes sense for the user, (vs the source code which is organized in a way that makes sense for the code).
My vote is to use all 3.
I also vote against wiki. Gh-pages should be easy to contribute to and allow for docs to be added to non-latest pieces of code.
Wikis can get too cluttered as they grow to encompass the "edge cases" that exist from version to version.
Sounds good @LongLiveCHIEF