Once introductions and preliminary explanations to the concept are made, you are ready to start diving into the code.
Make sure that you've already explained the significance of what tools, packages and languages that are needed. Tailor the explanation to the target audience. Throughout this instructional portion of the blog, keep in mind the language and tone of the supporting code documentation.
- Avoid large code chunks. Break them down into smaller, bit-sized pieces. Explain everything.
- Going from the last step to this step, did that particular variable assignment make sense? What was the purpose on the parameter being passed in? What was the output seen instead?
- If pseudocode is possible, introduce that first.
-
Explain the syntax and its nuances. Include links to its proper documentation.
-
Attach screenshots
-
Document everything that is happening.
-
Address any potential errors that may arise and causes. (i.e. placement of quotes, indentation, extra/missing bracket)
-
What is a similar approach? Is there a synonymous command to perform the same function?
-
This is a crucial teaching moment. Code snippet outputs help explain the bigger picture, getting from point A to Z.
-
Running the code, what should the reader expect to see and why are they seeing it? Verify the purpose of the command used again if it may be unclear.
-
Attach screenshots
-
There is sense of pride or accomplishment getting code to work. Let the users know what the end result should look like. If they're able to reproduce, you did a good job explaining!
-
Attach screenshots