Documentation for all
For your future self
Documentation should be written with the understanding that you’ll forget.
- Your future self will not have the same memorized head space of the code base
- Make everything clear & understandable
- If you did something weird: write a comment
Document all possibilities
Every possibility should be fully explored.
- Document all the available classes for a pattern
Document all the editable fields for a pattern
- Document for yourself: are you going to remember all the classes you can use?
Examples, examples, examples
Give examples when there’s possibility of confusion.
Our pattern library helps because it shows visible & code examples already
Will you remember how to use each pattern properly?
Context is (yas) queen
It’s important that readers understand the purpose of the documentation.
Provide enough details to explain when & why something should be used
Our pattern libraries already provide some context because they have a sole purpose
Use consistent language
Stick to active and consistent language & verbs.
- “Choose this pattern for banners at the top of all product categories.”
- “Never use this button style for forms.”
.highlightclass only when the dinosaur is featured.”
- Very similar language to our commits.
The readme is a good place to start documentation.
- Readmes help people get started
- Use a readme to introduce concepts & contexts
- The readme should act like a summary & table of contents
- Use the readme to explain the installation process