Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Writing Concepts

      +

      A concept explains to the user the why behind a procedure or piece of reference material. It explains what things are and introduces the things a user needs to know to be successful at completing a procedure or understanding references.

      Description Attribute

      At the beginning of every concept, you should have a brief explanation of the goal of the concept, or what the user can hope to learn from reading this concept.

      This goal should be part of the :description: attribute that you need to add to the beginning of every topic.

      If you need to add links to your brief explanation, put them outside of the :description: attribute.

      General Guidelines

      A concept should:

      • Explain all technical concepts or jargon, or link to other explanations if there isn’t space.

      • Use headings to break up and highlight important information to the user, to aid scanning and findability.

      • Link to related procedures or reference material.

      • Explain only one focused topic.

      • Have paragraphs of 5 sentences or less.

      Required Sections

      The only required heading and section in a concept is the See Also section.

      See Also

      The See Also section in a concept should be an H2 level heading.

      It contains an unordered list of links to tasks, references, or other concepts that the user can read to continue in their learning journey.

      There will always be somewhere the user can go next or view after reading your concept.