Though procedural in nature, tutorials provide more supporting information than help topics. A tutorial focuses on the detailed scenario steps, but also provides an introduction to the entire use case to ensure that users understand the purpose of that process.

• For tutorial titles, apply the same rules as for task titles.

  For example: Configuring a remote repository as a source for a File data set
  For example: Configuring a topic detection model for discovering keywords
  For example: Referencing remote repository data in a data flow

• Use the first 2-3 sentences in your tutorial to engage users and to make them want to read more!

  The short description should answer the following questions:

  • What is the business value of this task?
  • What can I achieve by performing this task?
  • What are the benefits of the feature I am about to use?
  • Why should I perform this task?
  • When should I perform this task?
  • Do I need to do anything else after I complete that tutorial?
  • How long will it take me to complete this tutorial?

  Note: Do not add a section title to this part.
  For example:

  
  For example:

  
• Optional:

  If your tutorial is a complex article with several procedures and many sections, add a list of links to these parts so that users can navigate through the document. Divide complex articles into more compact and stand-alone tutorials and provide linking between them.

  For example:

  

• To ensure that users can relate to the story that you outline, in the Use case section, clearly describe the context of the task, including:

  • Business context (the release of a new product, a special marketing campaign, etc.)
  • Fictional but themed company name
  • User type
  • Reason for performing the task
  • Goal to be achieved

  Ensure that you use that data consistently in the tutorial steps for records and file names. Do not use default or generic names. For more information, see Fictitious information in examples in text, images, and code examples.

  For example:

  
  For example:

  
  For example:

  

• List prerequisites that users need to know, do, or have access to before starting the tutorial, including learning specific terminology, completing other processes, passing an exam, or gathering specific files. List them concisely as bullets or numbered steps, depending on whether you list tasks or items.

  For example:

  

• When you describe a procedure that is the core of a tutorial, follow these guidelines:

  1. For section titles, enter the procedure name, starting with a gerund.

  2. For tutorials with more than one procedure, add a main process section with a list of links and nest the procedures underneath.

  3. Write steps in the same way that you write DITA tasks in terms of wording, styling, and grammar.

  4. Provide customized values for any parameters and options that you describe in the steps.

     Remember to make the scenario realistic by ensuring that the whole tutorial mentions the same data related to the fictitious company.

  5. Use meaningful visual aids to facilitate the understanding of more complicated steps and relationships.
  6. Optional:

     Summarize the steps by creating a featurette video.

  7. If you can divide a long tutorial into smaller, stand-alone procedures, create separate tutorials and gather them under the main article. Provide a link back to the container article from every shorter tutorial.

  For example:

  

• Use the Conclusion section to describe in 2-3 sentences what the user has accomplished by completing the tutorial.

  The Conclusions section serves as a typical DITA task result.
  For example:

  
  For example:

  
• Optional:

  Insert a frequently asked questions section to provide short and concise answers to questions about the tutorial or the feature it describes.

  The questions can include the following concepts:

  • Process context
  • Business value
  • Process details
  • Unusual circumstances
  • Security concerns

  List these questions in a bulleted list, and answer them in a maximum of two sentences. Always provide links to articles, tutorials, and help topics that provide more details.

• For information on which styles to use when writing tutorials, see Style guidance when writing content.

• Because you use a customized system, specific customer data, and dedicated parameters, you do not need to add any additional examples; the summary screenshots showing the setup that is applicable to your scenario provide enough guidance. However, an additional sample or two can help users understand the steps, so you can add them, but ensure that you stay on the happy path.

• When writing a tutorial, think of linking as being part of a content map in which the tutorial is the center and the referenced documents are remote but connected satellites. Because linking and navigation are crucial aspects of a tutorial, ensure that you help users navigate both inside and outside the center by applying the following principles:

  1. If any specific knowledge is necessary to perform the tutorial, link to prerequisite courses on Pega Academy, help topics, or other Pega Community articles.

  2. For more complex articles, provide internal links at the beginning of the article in the main procedure section. Add "Back to top" links from every section.

  3. For sets of tutorials that are part of a larger scenario, link between them by adding the "Before you begin" link after the "Use case" section and the "What to do next" link instead of the entire "Next steps" section. Provide a short intro to these tutorials by specifying the tasks that they describe.

     For example:

     
     For example:

     

  4. Supplement steps with links to help topics.

  5. Do not link to specific third-party documents. If necessary, provide a link to the main website of the vendor.

  6. Refer to the following tutorials as templates:

     • Tutorial: Configuring a topic detection model for discovering keywords
     • Tutorial: Configuring a remote repository as a source for a File data set
     • Tutorial: Using managed data flow runs