-
Notifications
You must be signed in to change notification settings - Fork 22
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
DOC-406: new tutorial template with guidance (#444)
Feedback actioned and guidance text clearly marked
- Loading branch information
1 parent
2f33634
commit c401fc8
Showing
1 changed file
with
58 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |