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 Procedures

      +

      A procedure can be:

      A how-to guide

      How-to guides explain to the user how to accomplish a goal without a specific, defined end result. The specifics of the end result will vary depending on the individual user’s goal. For example, a how-to guide could explain how to create a database by explaining the different options and customizations the user can make.

      A tutorial

      Tutorials explain to the user how to accomplish a goal that has a defined end result. All users that follow the tutorial will have the same result. For example, a tutorial could explain how to create a specific kind of database that would support a specific use case for the user.

      Description Attribute

      Before the Prerequisites section, you should have a brief explanation of the goal of the procedure, or what the user can hope to accomplish once they’ve completed the procedure.

      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.

      Required Sections

      All procedures should contain 3 section headers:

      1. Prerequisites

      2. Procedure

      3. Next Steps

      Prerequisites

      The Prerequisites section should be an H2 level heading.

      It contains an unordered list of things the user must do or have before they can proceed with the content in Procedure.

      There will always be something the user can do.

      Add links where appropriate, following the appropriate link formatting guidance.

      Procedure

      The Procedure section should be an H2 level heading that follows the Prerequisites section.

      It contains an ordered list of steps the user must take to complete the specific goal of the page.

      Steps in a Procedure section should:

      • List only one action per step, with the exception of using an Menu UI Macro for menu navigation steps.

      • Start with the location where the following action or actions need to occur. This could be the start of the step, or the start of the procedure itself, with menu navigation.

      • Use button macros for all Buttons.

      • Use keyboard macros for all keyboard interactions.

      • Use monospace font for all code outside of code blocks, SQL++ commands, function names, file paths, filenames, and text the user must input.

      • Use Bold for single menu items, tab names, and dialog names.

      Steps in a Procedure section shouldn’t:

      • List the result of an action, if the result is obvious. For example, the Create Project window appears after you click Create Project.

      • Contain lengthy explanations for the reason behind a step. Link to explanatory documentation, such as a concept, where necessary.

      Next Steps

      The Next Steps section should be an H2 level heading that follows the Procedure section.

      It contains either an:

      • Unordered list of links.

      • Running text that describes the next procedure or action the user can take.

      The Next Steps section is where additional procedures in a series or links to additional reading on other documentation pages should live.

      Always add links to a Next Steps section.

      Don’t call the section See Also, Additional Resources, or similar. There’s always some action the user can take after they complete a procedure.