-
-
Notifications
You must be signed in to change notification settings - Fork 3.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a style guide for documentation. Addresses #6178 #6206
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for putting this together, it looks good to me! I added a few notes that don't require any changes here but are just things we might want to be aware of when considering the rest of the docs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for writing such a comprehensive style guide! I added a few comments, mostly in the 'accessibility' session.
I think so! This should be a really helpful document for new contributors. One question that came up for me, would it be helpful to address how to handle assets in documentation and reference examples? This is something I've been unsure of in the past as a contributor and might save someone from doing guesswork, from what I understand, assets are stored in: Examples: Also, it might be worth noting that local assets would be preferable to external ones. |
@aceslowman great suggestion. I'll draft a guideline for including paths in the form |
Addresses #6178
Changes:
I drafted a style guide for documentation in contributor_docs/documentation_style_guide.md and would love to incorporate suggestions.
Should I open a separate PR for examples of edited documentation?
@wong-justin @aferriss @aceslowman would the proposed style guide suit your needs for WebGL documentation?
What are people's thoughts about requiring
describe()
throughout the documentation? Two possibilities come to mind:describe()
in all Examples and Reference code samplesdescribe()
in all ExamplesPR Checklist
npm run lint
passes