Skip to content
/Tutorials

September 17th, 2020

Writing a Technical Tutorial to Support the Open Source Community

  • portrait of Emma Jade Wightman

    Emma Jade Wightman

You are working on an awesome project, but nobody knows how to use it. The chance of someone discovering and using your awesome code goes up greatly with good documentation, tutorials and guidance!

This is a guide to writing an open source technical tutorial. The first time is always the most challenging, but we hope to get you started along the right path!

Where do I start?

Imagine that you are building a bridge for other developers to cross. On one shore stand your readers, safe in the land of existing knowledge. Your task is to create a safe passage over a vast plain of uncertainty to a place of newfound understanding.
Sample code, citations, diagrams and images, and other certainties are the towers spanning the plain. Your outline determines the order and distance between these structures and your job in the article itself is to fill each gap with explanation, the "why's" and intuition.
Each time you sit down to write, focus your attention on one distinct part of your tutorial. With only your outline, research, and relevant code in front of you, write a section in simple, straightforward words. Try not to get hung up on making the language elaborate, just get the words on the page. It will be much easier to adjust your work when you have a piece to edit. You've got this!

What should I write about?

  • Think of a topic that you find interesting and would like to read about.

  • Learn something new and write about it. Starting as a beginner gives you the advantage of seeing the topic with fresh eyes.

  • Dig deeper into an existing tutorial/guide topic and provide additional learnings.

  • Write about a project you're already working on, to get potential collaborators or contributors up to speed.

  • Check frequently asked questions on the community forum.

  • See what we're looking for on the "Contribute to Rasa" project board.

What is the difference between a tutorial and a guide?

A tutorial teaches the audience a new idea or concept by showing how to accomplish a goal. Tutorials take you through a technical process step-by-step and tend to get straight to the point.

A guide is usually focused on achieving a particular task and can assume some level of prerequisite knowledge. Like tutorials, they have a clear focus but also include cautionary advice and additional information. Guides may also suggest multiple approaches to accomplishing the task.

How should I format my post?

  • Format your code. Make sure your code is easy to read and distinguish from the rest of the text included in your text.
  • Use snippets. Most of the most popular content publishing platforms allow you to include code tags in your posts. Alternatively, you can include gists for longer code blocks.
  • Open source the full code on GitHub. 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 execute and test your projects easily without needing to copy or customize anything.

Example format:

  • Title
  • Introduction (& goals)
    • Usually 1-3 paragraphs long
    • What is the goal of the tutorial?
    • What software is involved, and what does each component do (briefly)?
    • What are the benefits of using this particular software in this configuration?
    • What are some practical reasons why the reader should follow this tutorial?
  • Prerequisites
    • What type of hardware or software is needed?
    • What experience level is the tutorial written for?
  • Step 1
  • Step 2
  • Steps continue...
  • Conclusion / Summary
    • What did we learn in this tutorial?
    • What will we learn in the next part of this tutorial?
    • Do you have a discussion thread to link to?

Where do I publish and promote it?

  • Rasa community forum. Post your guides and tutorials in our dedicated section for community tutorials and resources. Respond to posts where folks may have asked a question about this topic who could find your tutorial useful.

  • Blogging websites such as Medium & Dev.to. 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.

  • Promote on social media. Think Twitter, Facebook and especially professional networks like LinkedIn. Tag us @RasaHQ use the #RasaTutorial or #RasaGuide

  • Share it with the Rasa team. Shoot us an email at community@rasa.com

Tips:

  • If you get stuck trying to think of the perfect title, leave it for last! You can use a placeholder while you're writing and brainstorm titles when you have completed your write-up
  • Look to the forum for common questions. Covering a real issue will guarantee that people will find your tutorial useful and interesting. You can also ask for feedback on your tutorial on our community forum
  • Add comments to your code snippets. Make sure to properly annotate each snippet so that the reader can understand each step and why it's important.

Conclusion

At Rasa, we want you to write about things you are interested in, and we want you to have your own style. The way you write your post, your images, and your teaching style, is totally up to you! Be unique and enjoy the process of writing.
Helping others understand difficult topics and providing inspiration for interesting projects is a great way to become a contributor to Rasa open source! If in doubt, always feel free to reach out to us at: community@rasa.com