Looking to add another great tutorial to the Engineering Education blog? See a suggested structure below you can use and read our highlighted tutorial to discover the standard we're looking for.
Tip: Once, you've finished the first draft of your article, test every code snippet to make sure it works in isolation and in full. Uninstall and reinstall any packages you ask the reader to install as well to check your code works on a minimal environment since your readers will most likely have to install them too.
Here's an excellent tutorial written by one of our Eng-Ed Contributors so you can see the level of detail you should aspire to.
Before starting make sure you pinpoint the problem your article is going to solve for the audience. If you are writing a tutorial, it is because you have noticed a pain point you’d like to address. Usually this is a gap in the tutorials available. For example, there are no tutorials written about React from the perspective of a jQuery user.
To ensure the audience is getting the best experience - make sure you research other tutorials on the subject - this will help make you write a more complete and unique tutorial with a higher chance of being found and helping someone out. This also helps to narrow your focus as you research and begin to write. A bit of history about the technology being referenced or talked about might be helpful for the beginner audience.
When framing your tutorial it would help to identify your audience - who is this tutorial going to be written for - and who will be reading it.
Provide the audience a run down on what the article will be covering.
Provide the audience with any prerequisites that may be required to follow your tutorial. For example: Need basic HTML and CSS knowledge for an article on how to use the CSS pre-processor, Sass.
Tell the audience what a successful task looks like - and guide them through the process.
Make the tutorial as user-friendly as possible - by including screenshots, tips, code examples, anything you think would benefit the audience as they try to replicate the tutorial.
With supporting links, screenshots and code snippets (if images are from the internet provide sources). If your article is aimed at beginners, then make sure you provide enough detail for them to understand. Don't assume knowledge.
With supporting links, screenshots and code snippets (if images are from the internet provide sources). Make sure to use current technology. Try not to reference out-dated versions or depreciated packages.
With supporting links, screenshots and code snippets (if images are from the internet provide sources). If you mention any surrounding technology, that won't be explained in detail, add a link so curious readers can find out more.
Include any next or final steps summarizing the tasks the audience just completed with possible next steps. A further tutorial, for example or provide ideas for future projects using the technology