cameradar/.github/instructions/markdown.instructions.md

description, applyTo

description	applyTo
Documentation and content creation standards	**/*.md

Markdown Content Rules

The following markdown content rules are enforced in the validators:

1. Headings: Use appropriate heading levels (H2, H3, etc.) to structure your content. Do not use an H1 heading, as this will be generated based on the title.
2. Lists: Use bullet points or numbered lists for lists. Ensure proper indentation and spacing.
3. Code Blocks: Use fenced code blocks for code snippets. Specify the language for syntax highlighting.
4. Links: Use proper markdown syntax for links. Ensure that links are valid and accessible.
5. Images: Use proper markdown syntax for images. Include alt text for accessibility.
6. Tables: Use markdown tables for tabular data. Ensure proper formatting and alignment.
7. Line Length: Limit line length to 400 characters for readability.
8. Whitespace: Use appropriate whitespace to separate sections and improve readability.
9. Front Matter: Include YAML front matter at the beginning of the file with required metadata fields.

Formatting and Structure

Follow these guidelines for formatting and structuring your markdown content:

• Headings: Use ## for H2 and ### for H3. Ensure that headings are used in a hierarchical manner. Recommend restructuring if content includes H4, and more strongly recommend for H5.
• Lists: Use - for bullet points and 1. for numbered lists. Indent nested lists with two spaces.
• Code Blocks: Use triple backticks to create fenced code blocks. Specify the language after the opening backticks for syntax highlighting (e.g., csharp).
• Links: Use [link text](URL) for links. Ensure that the link text is descriptive and the URL is valid.
• Images: Use ![alt text](image URL) for images. Include a brief description of the image in the alt text.
• Tables: Use | to create tables. Ensure that columns are properly aligned and headers are included.
• Line Length: Break lines at 80 characters to improve readability. Use soft line breaks for long paragraphs.
• Whitespace: Use blank lines to separate sections and improve readability. Avoid excessive whitespace.

Follow our Guidelines

Spelling

In cases where American spelling differs from Commonwealth/"British" spelling, use the American spelling.

Although non-American readers tend to be tolerant of reading American spelling in technical documentation, they may find it difficult to have to type American spelling. For example, if your documentation tells a reader who's used to the spelling colour to type color, they may mistype it. So when you use filenames, URLs, and data parameters in examples, try to avoid words that are spelled differently by different groups of English speakers.

Write accessibly

Ease of reading

• Do not force line breaks (hard returns) within sentences and paragraphs. Line breaks might not work well in resized windows or with enlarged text.
• Break up walls of text to aid in scannability. For example, separate paragraphs, create headings, and use lists.
• Prefer short sentences.
• Define acronyms and abbreviations on first usage and if they are used infrequently.
• Place distinguishing and important information of a paragraph in the first sentence to aid in scannability.
• Use clear and direct language. Avoid the use of double negatives and exceptions in exceptions.

Bad	Good
A missing path will not prevent you from continuing. Double negation (missing, not) Use of future tense (will)	You can continue without a path.

Headings and titles

Use descriptive headings and titles because they help a reader navigate their browser and the page. It's easier to jump between pages and sections of a page if the headings and titles are unique.

• Use a heading hierarchy.
• Do not skip levels of hierarchy (h3 can only exist under h2)
• Do not use empty headings
• Use a level-1 heading for the page title.
• Use sentence casing for titles and headings.

Links

• Use meaningful link text. Links should make sense when read out of context.
• Do not force links to open in a new tab or window, let the reader decide how to open links.
• When possible, avoid adjacent links. Instead, put at least one character in between to separate them.
• If a link downloads a file, indicate this action and the file type in the link text.

Bad	Good
Use meaningful link text like described [here](https://developers.google.com/style/link-text). Use meaningful link text. [See document.](https://developers.google.com/style/link-text) Use meaningful link text. https://developers.google.com/style/link-text	Use [meaningful link text](https://developers.google.com/style/link-text).

Images

• When possible, use SVG images over any other format, since they are significantly lighter while having perfect information.
• For every image, provide alt text that adequately summarizes the intent of each image.
• Most of the time, do not present new information in images; always provide an equivalent text explanation with the image. There are of course exceptions for that, such as architecture diagrams, sequence diagrams etc.
• Do not repeat images.
• Avoid images of text, use text instead.

Tables

• Introduce tables in the text preceding the table.
• Avoid using tables to lay out pages.
• If the table contains only a single column, use a list instead.
• Do not put tables in the middle of lists or sentences.
• Sort rows in a logical order, or alphabetically if there is no logical order.

Use the active voice

In general, use the active voice instead of the passive voice. Make it clear who is performing the action. When using passive voice, it is easy to neglect to indicate who or what is performing the described action. In this kind of construction, it is often hard for readers to figure out who is supposed to do something.

Bad	Good
The service is queried, and an acknowledgment is sent. The service is queried by you, and an acknowledgment is sent by the server.	Send a query to the service. The server sends an acknowledgment.

Exceptions

In certain cases, it makes more sense to use the passive voice.

• To emphasize an object over an action.
• To de-emphasize a subject or actor.
• If your readers do not need to know who is responsible for the action.

Bad	Good
You created over 50 conflicts in the file.	Over 50 conflicts were found in the file.
The system saved your file.	The file is saved.
A system administrator purged the database in January.	The database was purged in January.

Write for a global audience

• Provide context. Do not assume that the reader already knows what you're talking about.
• Avoid negative constructions when possible. Consider whether it's necessary to tell the reader what they can't do instead of what they can.
• Avoid directional language (for example, above or below) in procedural documentation. This increases maintenance costs and could lead to future modifications breaking the documentation.

Here are some examples.

Bad	Good
This document makes use of the following terms: Can be substituted for a simpler verb.	This document uses the following terms:
A hybrid cloud-native DevSecOps pipeline Too many nouns as modifiers of another noun. Can be broken into two parts.	A cloud-native DevSecOps pipeline in a hybrid environment
Only request one token. Misplaced modifier, makes the sentence less clear and more ambiguous.	Request only one token. Request no more than one token. Request a single token.
If you use the term green beer in an ad, then make sure that it is targeted. Here, "it is" becomes ambiguous. It could describe the green beer or the ad.	If you use the term green beer in an ad, then make sure that the ad is targeted.

Use present tense

In general, use present tense rather than future tense; in particular, try to avoid using will where possible.

Bad	Good
Send a query to the service. The server will send an acknowledgment.	Send a query to the service. The server sends an acknowledgment.

Sometimes, of course, future tense is unavoidable because you're actually talking about the future (for example, This document will be outdated once PR #12345 gets merged.). Attempting to predict the future in a document is usually a bad idea, but sometimes it's necessary.

However, the fact that the reader will be writing and running code in the future isn't a good reason to use future tense.

Also avoid the hypothetical future would—for example:

Bad	Good
You can send an unsubscribe message. The server would then remove you from the mailing list.	If you send an unsubscribe message, the server removes you from the mailing list.

Use clear, precise, unambiguous language

• Use simple words. For example, do not use words like commence when you mean start or begin.
• Define abbreviations. Abbreviations can be confusing out of context, and they don't translate well. Spell things out whenever possible, at least the first time that you use a given term.

Be consistent

If you use a particular term for a particular concept in one place, then use that exact same term elsewhere, including the same capitalization.

• Use standard English word order. Sentences follow the subject + verb + object order.
• Try to keep the main subject and verb as close to the beginning of the sentence as possible.
• Use the conditional clause first. If you want to tell the audience to do something in a particular circumstance, mention the circumstance before you provide the instruction.
• Make list items consistent. Make list items parallel in structure. Be consistent in your capitalization and punctuation.
• Use consistent typographic formats. Use bold and italics consistently. Don't switch from using italics for emphasis to underlining.
• Avoid colloquialisms, idioms, or slang. Phrases like ballpark figure, back burner, or hang in there can be confusing to non-native readers.

Describe conditions before instructions

If you want to tell the reader to do something, try to mention the circumstance, conditions, or goal before you provide the instruction. Mentioning the circumstance first lets the reader skip the instruction if it doesn't apply.

Bad	Good
See [link to other document] for more information. Click Delete if you want to delete the entire document. Using custom domains might add noticeable latency to responses if your app is located in one of the following regions:	For more information, see [link to other document]. To delete the entire document, click Delete. If your app is located in one of the following regions, using custom domains might add noticeable latency to responses:

Use lists

Introduce a list with the appropriate context. In most cases, precede a list with an introductory sentence.

• Use simple numbered lists for steps to be performed in order.
• Nested sequential lists can detail sub-steps as well.
• Use bulleted lists when there are no sequences or options.

Use code blocks

In most cases, precede a code sample with an introductory sentence.

• Do not use tabs to indent code; use spaces only.
• Wrap lines at 80 characters if you need to, but try to use shorter lines in code blocks.
• Specify the code block language, for syntax highlighting.
• If the code block is meant to show a command being run, prefer showing the expected output if applicable.

Markdown guidelines

Add spacing to headings

Prefer spacing after # and newlines before and after.

...text before.

# Heading 1

Text after...

Use lazy numbering for long lists

Markdown is smart enough to let the resulting HTML render your numbered lists correctly. For longer lists that may change, especially long nested lists, use lazy numbering.

1.  Foo.
1.  Bar.
    1.  Barbaz.
    1.  Barbar.
1.  Baz.

However, if the list is small, and you don’t anticipate changing it, prefer fully numbered lists, because it is nicer to read in source.

Long links

Long links make source Markdown difficult to read and break the 80 character wrapping. Wherever possible, shorten your links. If it is not possible, feel free to reference links at the bottom of the paragraph instead:

This paragraph's lines would get very long and difficult to wrap if the [full link] is included inline.

[full link]:https://www.reallylong.link/rll/BFob89Cv/Owa_TbBBi3Bn9/n5cahxQtC4TOH/afoPnUDyyOS/_8Ilq4zSBjqmo8w/j6UN1uviS9zky

Prefer lists to tables

Any tables in your Markdown should be small. Complex, large tables are difficult to read in source and most importantly, a pain to modify later.

Lists and subheadings usually suffice to present the same information in a slightly less compact, though much more edit-friendly way.

Here is a bad example:

Fruit | Attribute | Notes
--- | --- | ---
Apple | [Juicy](https://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away.
Banana | [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.

And here is a better alternative:

## Fruits

### Apple

* [Juicy](https://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
* Firm
* Sweet

Apples keep doctors away.

### Banana

* [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
* Soft
* Sweet

Contrary to popular belief, most apes prefer mangoes.

Strongly prefer Markdown to HTML

Please prefer standard Markdown syntax wherever possible and avoid HTML hacks. If you can not seem to accomplish what you want, reconsider whether you really need it. Except for big tables, Markdown meets almost all needs already.

Every bit of HTML or Javascript hacking reduces the readability and portability. This in turn limits the usefulness of integrations with other tools, which may either present the source as plain text or render it.

Spacing

• Remove all trailing whitespaces at end of lines.
• Remove instances of multiple consecutive blank lines.
• Files should end with a single newline character.

Validation Requirements

Ensure compliance with the following validation requirements:

• Front Matter: Include the following fields in the YAML front matter:

  • post_title: The title of the post.
  • author1: The primary author of the post.
  • post_slug: The URL slug for the post.
  • microsoft_alias: The Microsoft alias of the author.
  • featured_image: The URL of the featured image.
  • categories: The categories for the post. These categories must be from the list in /categories.txt.
  • tags: The tags for the post.
  • ai_note: Indicate if AI was used in the creation of the post.
  • summary: A brief summary of the post. Recommend a summary based on the content when possible.
  • post_date: The publication date of the post.

• Content Rules: Ensure that the content follows the markdown content rules specified above.

• Formatting: Ensure that the content is properly formatted and structured according to the guidelines.

• Validation: Run the validation tools to check for compliance with the rules and guidelines.

Admonitions

Use GitHub-flavored markdown for admonitions: NOTE, WARNING, TIP, IMPORTANT, CAUTION.

Examples:

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.