Writing

English is the language we code in to modify the brains of our coworkers. As for any programming language, it’s worth putting effort into improving your proficiency.

This section lists a few guidelines for our docs. You can learn more about best practices for technical writing, in general, from articles such as Technical writing style.

PREFER

PREFER brevity

Be clear and precise, but also terse.

PREFER using “this” instead of “the” to refer to a member’s instance

When documenting a member for a class, you often need to refer back to the object the member is being called on. Using “the” can be ambiguous.

class Box { 
   /// The value this wraps. 
   var _value; 

   /// True if this box contains a value. 
   bool get hasValue => _value != null; 
}

AVOID

AVOID abbreviations and acronyms unless they are obvious

Many people don’t know what “i.e.”, “e.g.” and “et al.” mean. That acronym that you’re sure everyone in your field knows may not be as widely known as you think.