DevRel-X : Building Tutorials for your developers

When you’re building a product, it’s important to have good documentation. Documentation helps your developers understand your product and use it effectively. It also helps you keep track of your product’s features and functionality. But what goes into writing good documentation? In this blog post, we’ll discuss how to write tutorials for developers.

Building_Tutorials_for_your_developers_-_Instagram_Post.png

A tutorial is a type of document that walks the reader through a task step-by-step. A tutorial can be as simple as a few paragraphs or as long as a multi-part series. The important thing is that it is clear, concise, and easy to follow.

You should write a tutorial anytime you need to explain how to do something. This could be how to use your product, how to install your product, or even how to troubleshoot common problems. By having clear and concise tutorials, you can save your developers time and frustration.

Now that we’ve discussed what a tutorial is and when you should write one, let’s talk about how to actually write a tutorial.

The first step is to decide what format your tutorial will take. Will it be text only? Will you include screenshots? Will you use video? Code Samples? Once you’ve decided on the format, you can start writing your tutorial.

When writing your tutorial, it’s important to keep the following things in mind: • Keep it simple – Use short sentences and small paragraphs. And don’t forget to break up your text with headings and subheadings so it’s easy to scan.

• Use concrete examples – Wherever possible, use concrete examples to illustrate your points. This will help your readers understand the concepts you’re trying to explain.

• Be clear and concise – Be sure that your instructions are clear and concise. If something isn’t clear, chances are your readers will get lost (and frustrated).

• Edit and proofread / Test Code Samples – Before you publish your tutorial, be sure to edit and proofread it carefully. Nothing undermines credibility like typos and grammatical errors! By following these tips, you can write clear and concise tutorials that will help your developers (and other users) understand and use your product more effectively. Use automated test tools to test your code samples.

One way to validate the tutorials and check for correctness/receive feedback is by introducing “Was this helpful / Rate this tutorial ” section in the Dev Hub/ Documentation page. There should be a way for Developers who read/review the tutorials to suggest edits/ provide feedback and this should be made available for them in an easy , simple and less time consuming way.

  • You could provide links to edit /send PR to tutorials via Github

  • Suggestions section where you could collect inputs

  • Ratings the tutorials

  • Opening discussions on your community forum / GitHub to collect feedback

  • You could find the confidants in your dev community (DevRelX , Avocado )/ internal engineering team and share these tutorials and ask for their feedback

  • Running recurring survey ( traditional surveys ) with your dev community

Writing tutorials may seem like a daunting task, but it doesn’t have to be! By following the tips in this blog post, you can write clear and concise tutorials that will help your developers (and other users) understand and use your product more effectively. Do you have any tips for writing tutorials? Share them in the comments below!