DEV Community

Cover image for Writing Software Tutorials for Beginners - 10 Tips, Tricks, and Rules I Follow
Andrew Baisden
Andrew Baisden

Posted on

9 1 1

Writing Software Tutorials for Beginners - 10 Tips, Tricks, and Rules I Follow

My writing journey began in 2020, and over the years, I have refined my strategy and learned many different techniques and writing styles. I started by writing many articles for free on my blogs and then moved on to writing many articles for various clients as my knowledge and experience in this industry grew.

Taking all of this into account, I have put together a list of 10 tips and tricks that I have been following. These have allowed me to create consistently good articles over the years, which are often shared on social media and help other people in the tech industry learn.

1. Write like you are a beginner

It's a good strategy to write your articles as if you are reading them for the first time and have no idea what they are about. This can make the content much more uncomplicated to digest and understand. I aim to limit the time the reader spends doing external Google searches because they don't understand some of the concepts you are discussing.

2. Explain every code block

Writing a code summary or explaining what a code block is doing is extremely helpful and a great way to avoid that copy-and-paste situation where you are copying code and following a tutorial. Still, you don't really understand what that code is doing. This in itself can lead to "tutorial hell".

3. Create run scripts

If you're creating a tutorial from scratch, the reader will likely have to go through the entire build stage. It is far too tedious to have the reader manually cd into this folder and then create all of the files one by one. Instead, I prefer to make a run script that the reader can copy and paste into their terminal, run, and then it will set up the whole project for them. Then, all that is left is the codebase.

4. Put the codebase on GitHub

Putting the complete codebase on GitHub means that the reader has access to the entire code right from the start and can see the entire project. This saves a whole lot of time, and it means that the reader does not have to go step by step through the tutorial themselves if they don't want to or don't have the time.

5. Show a screenshot of the final application

People want to know what they are building, so if you have a screenshot of the final applicationβ€”or, better yet, screenshots of every page or screenβ€”that helps the reader visualise what they are making.

6. Have a link to the live application online

When the final application is deployed online, the reader can watch the live demo to get a feel for what they will be building. This can be even better than looking at static screenshots.

7. Write the article in Markdown if you can

Markdown is the best language for writing articles. The language is powerful, and you can easily publish the article online on many platforms, including GitHub, without having to modify any of the code. However, if you have clients, some might prefer that you write in Microsoft Word. If it's a text-based article, then it's not a big issue; however, if you have lots of code blocks, then writing them in a Word document is not as convenient because of the formatting and text highlighting issues that arise.

8. Check spellchecking and grammar

When writing, try to be professional. Double-check your spelling and grammar, and proofread your work. I like to use Grammarly because it is excellent at cleaning up early drafts and enhancing wording so the writing flows better.

9. Show the project structure

Being able to see the project structure makes it far easier to understand the architecture and how everything works. Files, folders and structure can be easily outlined in a nice overview.

10. Use images, charts or infographics

Make your article as beautiful as possible if you can. Include images to show the application or animated gifs to bring some life to the piece that the reader is reading. Charts can help when explaining something related to data, and infographics and other diagrams can break down and explain complex concepts.


Stay up to date with tech, programming, productivity, and AI

If you enjoyed these articles, connect and follow me across social media, where I share content related to all of these topics πŸ”₯

https://res.cloudinary.com/d74fh3kw/image/upload/v1736534789/header-2025-v1_vehh5c.png

Speedy emails, satisfied customers

Postmark Image

Are delayed transactional emails costing you user satisfaction? Postmark delivers your emails almost instantly, keeping your customers happy and connected.

Sign up

Top comments (2)

Collapse
 
madza profile image
Madza β€’

Always awesome to receive some experience-based insights from writers like you! Keep up the great job, mate!

Collapse
 
andrewbaisden profile image
Andrew Baisden β€’

Thanks as always, much appreciated πŸ‘

Eliminate Context Switching and Maximize Productivity

Pieces.app

Pieces Copilot is your personalized workflow assistant, working alongside your favorite apps. Ask questions about entire repositories, generate contextualized code, save and reuse useful snippets, and streamline your development process.

Learn more

πŸ‘‹ Kindness is contagious

Discover a treasure trove of wisdom within this insightful piece, highly respected in the nurturing DEV Community enviroment. Developers, whether novice or expert, are encouraged to participate and add to our shared knowledge basin.

A simple "thank you" can illuminate someone's day. Express your appreciation in the comments section!

On DEV, sharing ideas smoothens our journey and strengthens our community ties. Learn something useful? Offering a quick thanks to the author is deeply appreciated.

Okay