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.”

• “Add the .highlight class only when the dinosaur is featured.”

• Very similar language to our commits.

The README

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

Videos & tutorials

• Writing a readme ➔
• Writing better documentation ➔
• Documentation checklist ➔