Skip to content

Commit

Permalink
DOC-406: new tutorial template with guidance (#444)
Browse files Browse the repository at this point in the history
Feedback actioned and guidance text clearly marked
  • Loading branch information
amandalindsay authored Mar 6, 2025
1 parent 2f33634 commit c401fc8
Showing 1 changed file with 58 additions and 0 deletions.
58 changes: 58 additions & 0 deletions templates/modules/tutorial-template.adoc
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit c401fc8

Please sign in to comment.