- Tutorials should be in English.
- If you're fluent in another language, and are able to make a translation, you can submit your tutorial in multiple languages, as long as at least one is English.
- If you're not fluent in English, but you have a great tutorial to share in a different language, please reach out to us. We are open to the possibility of making exceptions for specific tutorials.
- We will only accept original work.
- This means that you cannot re-submit any work that is published somewhere else on the the web.
- Write in a clear, easy to understand way.
- These tutorials will be read by users with a wide range of experience. Make sure beginners can still follow what is being done. This means it is important not to skip any steps, no matter how obvious or self-explanatory they may seem. Feel free to include screenshots, to show exactly what the user should be seeing.
- Jokes are allowed, but don't overdo it.
Tutorials should all have the same basic layout:
The title should make clear what the goal of your tutorial is. Don't stuff everything into the title though, this should be a summary that gives users an immediate idea of what the tutorial is about. e.g. Installing
The first paragraph or paragraphs are there for you to explain what your tutorial will do. Make sure users know exactly what they will end up with if they follow your tutorial, and let them know if they need any specific prerequisites. You can link to other tutorials that your tutorial builds on, and add recommendations for what users should know.
The "Steps" section is the actual set of steps users will take to complete your tutorial. Each step should build on the previous one until the final step finishes the task at hand. It is important not to skip any steps, no matter how obvious or self-explanatory they may seem. Feel free to include screenshots to show exactly what the user should be seeing. The amount of steps will depend entirely on how long/complicated the tutorial is.
At the end of your tutorial, once the user has completed all the steps, you can add a short conclusion. Summarize what the user has done, and maybe suggest different courses of action they can now take.
Tutorials should be written using Markdown. This is a markup language used all over the web. A great overview can be found on Github:
While the title should be a H1 header, all other headers should be H2. If there are two or more smaller steps within a larger step, you can consider making those smaller steps H3.
For specific examples of how to format a tutorial, please take a look at the template below.
You can create code examples in nearly every programming language. Just state the language after the first three backticks in your Markdown file.
s = "Python syntax highlighting" print s
Download Example: markdown_example.txt