Writing Guidelines

Writing Guidelines

This document represents some basic requirements and recommendations that will help you create grammatically correct and stylistically consistent documentation articles. The recommendations are based entirely on reviews of MAUI PRs and try to address some of the most common issues.

1. Write Meaningful Descriptions.

A meaningful description must answer the following questions:

• What is the described thing?
• What is the main objective of the article? What does the article tell? (Usually to learn something about a * component, feature, or property)
• What are the benefits of using the described component or feature?
• What are the use cases for this component or feature? What can you do with it?

2. Typos and Spelling

• Always use spaces between the words that precede or follow content in parentheses. For example, "the IsExpanded(bool)property" is missing a space.
• Write "Boolean" with a capital "B".

3. Watch Your Grammar

• Using the definite and indefinite articles.
• Using commas after a prepositional phrase at the beginning of a sentence. For example, "Through the Spacing (double) property, you can specify the distance between the Accordion items." A prepositional phrase is a group of words that begins with a preposition and includes a noun or pronoun, which is the object of the preposition: "In the park, the trees had lost their leaves."
• Use closing punctuation in the meta descriptions and insert a period at the end of the sentence.
• Use a comma at the end of the infinitive phrases. Infinitive phrases are formed by using the base form of a verb (infinitive) preceded by the word "to." For example, "To choose any of those modes, use the SuggestMode property of the control."

4. Watch Your Style

• Don't use bold for component or feature names.
• Use title-case capitalization in all headings and titles.