Add a style guide for documentation. Addresses #6178

[nickmcintyre]

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:

• Require describe() in all Examples and Reference code samples
• Require describe() in all Examples

PR Checklist

• npm run lint passes
• [Inline documentation] is included / updated

[davepagurek]

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.

[Qianqianye]

Thanks for writing such a comprehensive style guide! I added a few comments, mostly in the 'accessibility' session.

[aceslowman]

would the proposed style guide suit your needs for WebGL documentation?

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: src/data/examples/assets
Reference Pages: src/templates/pages/reference/assets
Learn Pages: src/assets/learn

Also, it might be worth noting that local assets would be preferable to external ones.

[nickmcintyre]

@aceslowman great suggestion. I'll draft a guideline for including paths in the form 'assets/file.xyz'. It will include a note on where to place those assets for different types of documentation.