From c401fc88bbb19cabd4993945b14a3679701302d4 Mon Sep 17 00:00:00 2001 From: Amanda Lindsay Date: Thu, 6 Mar 2025 13:04:03 +0000 Subject: [PATCH] DOC-406: new tutorial template with guidance (#444) Feedback actioned and guidance text clearly marked --- templates/modules/tutorial-template.adoc | 58 ++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 templates/modules/tutorial-template.adoc diff --git a/templates/modules/tutorial-template.adoc b/templates/modules/tutorial-template.adoc new file mode 100644 index 00000000..85edfa63 --- /dev/null +++ b/templates/modules/tutorial-template.adoc @@ -0,0 +1,58 @@ += Title of your tutorial topic +:description: (Enter a brief description of your tutorial in the description). + +== Overview + +{description} + +(This template includes writing instructions—this guidance is contained in '(brackets)'—and boilerplate text that you can customize, use as-is, or replace with your own text. To use the template, either copy and paste the contents, or save a copy of the file. + +In the Overview, include the learning objectives—these may be in the description—and some rough timings. For example:) + +Get started with the Hazelcast Python client and learn how to manipulate a map. The tutorial will take approximately 10-15 minutes to complete. + +(Ideally, your tutorial should take less than 60 minutes to complete as lengthy tutorials can overwhelm users. Consider condensing or removing steps or re-evaluating the scope of the tutorial. Optionally, you may also want to state the intended audience. + +For more general guidance on tutorials, see: https://gitlab.com/tgdp/templates/-/blob/main/tutorial/guide_tutorial.md[The Good Docs Project]) + +== Prerequisites + +(Use this section to tell users about any prerequisites needed before they start the tutorial, such as: + +- Expected prior knowledge +- Software or hardware to obtain +- Environments to set up and configure +- Access codes to obtain + +For example:) + +Before you begin, make sure you have the following: + +- Python 3.6 or above +- Hazelcast Cloud Account +- A text editor or IDE + +== (Title of your first step + +1. Steps typically include a paragraph or a numbered list of sub-steps. Don't use bulleted lists for instructions. +2. Explain any examples and note any placeholders that will need to be replaced with real values. +3. Don't number your step's main headings — for example, don't use 'Step 1 - Configure the thing'. +4. Avoid gerunds i.e. -ing words such as 'Configuring'. +5. Remember to orient users when guiding them through each step. If they need to open a particular file or dialog to complete the task, provide that information first.) + +== (Title of your second step + +1. Add steps until you complete the tutorial. +2. Include a final "clean up" step to reset any changes where appropriate, e.g. if the tutorial deploys resources in the cloud.) + +== Summary + +(Use this section to summarize what the user learned in the tutorial. For example:) + +In this tutorial, you learned how to get started with the Hazelcast Python Client, connect to an instance, and put data into a distributed map. + +== Next steps + +(Use this section to include links to related tutorials, documentation, or other relevant resources, typically in a bulleted list. For example:) + +For more information, such as how you can query a map with predicates and SQL, check out the Python Client repository and the Python API documentation.