Ideas and best practices for writing tutorials
Possible topics for workshops and tutorials include everything that makes the everyday life of users, developers, administrators and DevOps a little easier, such as:
- Automation and infrastructure as code: How do I design a setup according to the cattle instead of the pet principle? How do I use deployment frameworks such as Ansible, Terraform or Heat?
- Development and testing: Which best practices simplify work with a CI/CD pipeline? How can these processes be monitored? How can I conduct tests in a cloud environment?
- Data science, machine learning and artificial intelligence: How can I quickly build and manage frameworks such as pandas, TensorFlow or Keras? What CPU, memory, GPU and FPGA configurations work best?
- IoT and edge: How does the interplay between decentralized edge devices such as the Raspberry Pi and centralized queues such as Kafka and time series databases work? How can I analyze and visualize collected sensor data?
- Orchestration and containers: Which hints and tips help you get started with a microservice architecture? What is the best way to manage APIs? Which steps enable a smooth migration from mode 1 to mode 2?
Tips on structuring your tutorial
Ideally, the length of your tutorial should range between 5,000 and 15,000 characters. You can write the texts in German or in English. While our editorial team accepts all text and file formats, Markdown and reStructuredText are particularly welcome. A well-structured text is easier for readers to comprehend. If you observe the following tips when writing your tutorial, it will be easier to give it an effective structure.
- What is the context?
A general statement on the topic of the tutorial is a good way to start. Your readers should be able to wholeheartedly agree with this statement. For example: “Setting up a public cloud platform is a complex task, as there are many different components and processes to take care of.”
- Which challenge do you wish to solve?
Name the specific problem that your tutorial aims to solve. For example: “When using solution X, users are often confronted with the failure of component Y and spend a lot of time troubleshooting. This tutorial will get to the cause of the problem and provide a long-term solution.“
- What is your approach?
A brief summary of the solution will give the reader an initial overview and will make the procedure easier to understand. For example: “We have come up with a sophisticated monitoring solution that collects and stores data, visualizes trends and alerts the responsible teams when problems arise. We will describe these four steps in detail."
- What is your technical solution to this problem?
This is the main section of your tutorial and covers the largest part of it by far. Describe the step-by-step procedure to your readers.
- What is your conclusion?
What are the most important points of your tutorial? Do you have a call to action? Even when the readers can’t recall the details of your text – what is the key message that they should remember and pass on to others?
Recommendations on language and structure
Here are some tips on writing your tutorial. They might not apply in all situations, so exceptions are possible.
Structure your text – but don’t overdo it
Paragraphs and subheadings give your text a clearer structure. However, do not get carried away with too many different levels of subheadings that make your tutorial too complex. Try to stick to one heading for the entire document and one level of subheadings.
Use brief sentences
Long sentences are always difficult to read. Understanding them is particularly difficult if your readers are reading documents online on narrow mobile devices. Therefore, keep it short and sweet.
Use active voice
If you write in the passive voice, it may not be clear to your readers who or what the subject in the sentence is, making the sentence more difficult to understand. For example: “Once the user permissions have been updated in /etc/passwd, the administrator can log on to the system.” Better: “Once the XY script has updated the user permissions in /etc/passwd, the administrator can log on to the system."
Add tables, diagrams and images
Images and screenshots make a tutorial much clearer and easier to understand. Please add captions that explain what the image shows. Imagine you are describing the image to a blind person. It is not a problem if this description is three to four lines long, or if it repeats information from the main text.