How to write a technical tutorial
Contributing to open source goes far beyond code contributions. If you like creating educational content - tutorials, overviews, how-to’s, it could be your way to become an open source contributor. If you are new to contributing to open source and creating content for developers you probably have the same questions as most beginners have: How do I start? What should I write about? How to make people find my content?
To make this process easier, we wrote down some tips on how to create developer education content and become a contributor to Rasa!
Decide on what you want to write about
If you are a beginner in content creation, one of the biggest hurdles in getting started is choosing a topic. A very big misconception when choosing what to write about is the idea that if someone else already wrote about a specific topic, there is no point in covering again. No matter how much the topic has been covered before, you can always dig deeper, provide interesting real-world examples or find better ways to explain difficult concepts in your own words. The most important thing is to know what message you would like to send to the readers of your post and what you would like them to learn. So how do you pick a topic? Here are some ideas for you:
- Think of what YOU find interesting and would like to read about. Writing good technical content takes time and throughout research of the topic you want to cover. Writing about something you are curious about yourself will make it easy to dedicate yourself to research and writing.
-
Work on projects and write about them. Have you built a Rasa-powered assistant, made an interesting integration with other tools or tested Rasa’s performance against other tools? Write about it! Actual projects and real developer experiences are the best resources other developers can learn from.
-
Look through the questions people have on the community forum. It’s the best place to find what issues people have and what areas they need more information on. Covering a real issue will guarantee that people will find your tutorial useful and interesting.
-
Check out our contributor project board. From time to time, Rasa team will share some blogpost/tutorial ideas you can take on and write about.
If you picked the topic, but feel unsure if you should write about it or what points you should cover, feel free to shoot an email to communty@rasa.com with the outline of your post and we will share some feedback and guide you along the way.
Include code snippets where possible
While overviews and high-level blogposts are great for introducing new tools, to make your content really valuable for developers we would recommend you to include code snippets, examples or ideally end-to-end implementations of the projects you write about in your post. Here are some tips you might find useful when including code in your tutorials:
-
Break things down. It’s better to divide your code into smaller chunks and describe them step-by-step rather than including one big code file. This allows the reader to really understand what happens at each line of code and why it is necessary.
-
Add comments. When writing developer content, your goal should be to make sure that the reader can easily understand every concept and every line of code you include in your post. Adding comments will make it easier to follow and understand the content you write about.
-
Format your code. Make sure your code is easy to read and distinguish from the rest of the text included in your text. Most of the most popular content publishing platforms allows you to include code tags in your posts, alternatively, you can include code snippets as gists.
-
Consider adding GitHub repository with full code. While having code snippets in your tutorials helps to keep your readers engaged, it’s very valuable to create and reference GitHub repositories with full completed code. This allows your audience to run and test your projects easily without needing to copy or customize anything.
Pick a platform to publish your tutorial
There are different platforms you can use to publish your tutorials. It really depends on your preference where you would like to host your content, but if you are new to technical writing, we have some suggestions for which platforms you could use to get started:
-
Rasa community forum. If you like, you can write your tutorials directly on Rasa community forum. We have a separate category for community resources, so simply create a new topic using your post’s name as a title and write your content.
-
Medium. It’s a widely used platform where you can publish your tutorials free of charge. An advantage of using Medium is that it makes it easy for other people to find your tutorials amongst the relevant/recommended posts.
-
Your own blog/site. If you have your own blog/site, then you can publish your tutorials there and share the link to it with the community.
Share and promote your content
Once you have published your tutorial, it’s time to let the world know about it. Here are some places you should definitely share your content on:
-
Rasa community forum. It’s the place where Rasa community meets and we have a section dedicated for community tutorials and resources.
-
Share your tutorials with the Rasa team. Shoot us an email at community@rasa.com. Every month we pick the best community resources and feature them in our community newsletter and share on social media.
-
Your social media. Social media is a great way to share your developer education content with an even broader community so make sure to post your tutorial on twitter, linkedin or facebook and tag @RasaHQ so we can reshare it on our social media platforms too.
At Rasa, we want you to write about things you are interested in and we want you to have your own style. For that reason we don’t have restrictions on how your post should be written, what image or content style you should follow. Be unique and enjoy the process of writing. Helping others to understand difficult topics and provide inspiration for interesting projects is a great way to become a contributor to the Rasa open source project! If in doubt, always feel free to reach out to us at community@rasa.com.