You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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)...
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:
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.
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
The text was updated successfully, but these errors were encountered: