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. This article is a radically shortened version of the DevTools Style Guide.

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 * control, feature, or property)
• What are the benefits of using the described control or feature?
• What are the use cases for this control or feature? What can you do with it?

2. Write Meaningful Introductions

Every article must have an introductory sentence or a paragraph. This introduction is very similar to the meta description as it must answer almost the same questions:

• What is the thing you write about?
• What do you use it for?
• When do you use it?
• Why don't you use something else (describe the advantages of this thing)?

3. Avoid Typos and Spelling Errors

• 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".

4. Watch Your Grammar

• Use the definite and indefinite articles correctly.
• Use 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."

5. Watch Your Style

• Don't use bold for control or feature names.
• Use title-case capitalization in all headings and titles.
• Create lists and nested lists by following the guidelines. If a code block belongs to a list item, make sure to nest it.