README.md

Contributing to Dapr documentation

High quality documentation is a core tenant of the Dapr project. Some contribution guidelines are below.

Use sentence-casing for headers.
Check the spelling and grammar in your articles.
Use a casual and friendly voice—like tone as if you're talking to another person one-on-one.
Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share.
Use “you” rather than “users” or “developers” conveying friendliness.
Avoid the word “will”; write in present tense and not future where possible. E.g. Avoid “Next we will open the file and build”. Just say “Now open the file and build”
Avoid the word “we”. We is generally not meaningful. We who?
Avoid the word “please”. This is not a letter asking for any help, this is technical documentation.
Assume a new developer audience. Some obvious steps can seem hard. E.g. Now set an environment variable DAPR to a value X. It is better to give the reader the explicit command to do this, rather than having them figure this out.
Where possible give the reader links to next document/article for next steps.

Ensure the reader can understand why they should care about this feature. What problems does it help them solve?
Ensure the doc references the spec for examples of using the API.
Ensure the spec is consistent with concept in terms of names, parameters and terminology. Update both the concept and the spec as needed.
Avoid just repeating the spec. The idea is to give the reader more information and background on the capability so that they can try this out. Hence provide more information and implementation details where possible.
Provide a link to the spec in the Reference section.
Where possible reference a practical How-To doc.