Some feedback from @hcferguson and a few other folks I've talked to about the style guide: for those who aren't used to seeing GitHub a lot, they get lost and give up perusing the style guides because the page is full of github distractions instead of being focused on the style guides themselves. Moreover, updating the README is a constant chore (e.g. #82): because there's now several people writing the style guides, the manual update step means the README is constantly behind the guides.
This could be easily rectified by having the content of the style guides be on GitHub Pages. More concretely:
the README could be pared down to the intro paragraph plus a "follow this link to see the rendered style guides"
2a. GitHub Pages' built-in Jekyll support could be used since this is a static site.
2b. We can set up a lightweight CI build that either uses some other static site generator or just a dead-trivial script that uses pandoc or some other markdown-to-html converter to make the HTML pages for the guides.
Auto-generate an index / Table of Contents with whatever framework is chosen in 2
Downside is that this might be over-automating a problem that we should just instead use maintainer discipline to enforce (the README thing, I mean)...
arfon
commented
5 years ago
Some feedback from @hcferguson and a few other folks I've talked to about the style guide: for those who aren't used to seeing GitHub a lot, they get lost and give up perusing the style guides because the page is full of github distractions instead of being focused on the style guides themselves. Moreover, updating the README is a constant chore (e.g. #82): because there's now several people writing the style guides, the manual update step means the README is constantly behind the guides.
This could be easily rectified by having the content of the style guides be on GitHub Pages. More concretely:
2b. We can set up a lightweight CI build that either uses some other static site generator or just a dead-trivial script that uses pandoc or some other markdown-to-html converter to make the HTML pages for the guides.
Downside is that this might be over-automating a problem that we should just instead use maintainer discipline to enforce (the README thing, I mean)...
cc @arfon @stscicrawford