writing-docs.md

Writing docs

Decision

Use these guidelines when writing docs for components:

General

• Use British English for docs, US English for APIs and code interfaces. Documentation comments should use British English except when referring to API interfaces which should be quoted verbatim.

Titles

• Use sentence case.
• Keep titles to the singular form.

e.g. 'Bar chart’ over ‘Bar Charts’.

Intros

• Use plain English.
• Describe the component and its broad purpose - do not go into detail.
• Keep descriptions to no more than 100 words.
• Do not talk about the configurations.
• Keep the descriptions platform agnostic unless the component is strictly for one platform and will never apply to others e.g. Touchable Native Feedback is strictly for Android.
• Should you need to reference the component name mid sentence, use lower case.

Thinking

We want to ensure components are documented consistently and consumers have the right amount of information.