ANNOTATION OF AN ARTICLE EXAMPLE CODE

The following rules apply to all code annotations. Annotations apply to the code from the line below the comment tag to the next comment tag or the end of the code block.You can start with a blank annotation if you do not want to add an annotation to the first line of code. An annotated code example must start with a single line annotation.For example, # for YAML and // for JavaScript.

You must use the comment tag for the language that the code sample is written in. Add annotations using comment tags ( #, //, For example, ```yaml annotate or ```ruby annotate. Specify a language for the code example after the triple backtick, followed by annotate.Create a code example using triple backticks.Specify the layout: inline frontmatter property for the article.If you have multiple code examples in an article, consider whether they can be combined into a single example. You can annotate multiple code examples in a single article, but keep in mind that each annotation increases the complexity of an article and adds repetitive navigation tasks for people using screen readers. Annotations can explain why code was written a certain way so that the fundamentals are clear. Often, code annotations will be used to explain key concepts to new users or specific choices to more experienced users.įor new users, code annotations are a way to go beyond the high level overview of a code example and explain what each line of code does so that someone can understand the code as if a friend or coworker were guiding them through it.įor more experienced users, code annotations can help them understand a code example and then tailor it to their specific needs. Code annotations are not required for every code example and should only be used if there is a clear need for them.Ĭode annotations can be helpful for a variety of audiences.

ANNOTATION OF AN ARTICLE EXAMPLE FULL

We only annotate full code examples, not snippets. The annotations render next to the code example in a two pane layout, so we can write longer annotations without making the code itself difficult to read. Code annotations help explain longer code examples by describing what a code example does and why.

Annotation of an article example