Preparing a Technical Tutorial

This document is aimed to help you in creating a that has a more technical focus (i.e. it will include code samples and examples) if you’ve never created one before.

Preparation

Top ↑

Define a clear set of goals/learning outcomes

With technical tutorials for Learn WordPress, it’s always a good idea to make sure you define clear goals/learning outcomes. What are the specific tasks the learner will be able to do once they have completed the tutorial? This helps you define what you will include in the tutorial, and what you won’t.

Why is this important for technical tutorials? This is because often when teaching development concepts, one idea can lead down a bit of a rabbit hole, leaving the learner with more unanswered questions, which is not ideal.

For example, let’s say you want to create a workshop on WordPress HooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same.. There are a number of possible learning outcomes, some directly related to the main topic, some tangential, but required to present the main learning outcomes:

  • What are hooks?
  • What are the different types of hooks?
  • What are the differences between the different types of hooks?
  • How are hooks defined?
  • What is a hook callback function?
    • What is a function in PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php., and how do you create one
  • How do you register a hook callback function?
    • How do you add a custom PHP function to a WordPress site?
      • What is a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party?
      • What is a child themeChild theme A Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your theme. https://developer.wordpress.org/themes/advanced-topics/child-themes/.?
  • What is hook priority?
  • How do hooks work with arguments?
    • What are arguments in PHP, and how do they work?

If you tried to include all of this into one tutorial, it would end up being quite a bit to cover. Therefore you need to be selective about what you cover, and what could be covered in other tutorials.

During this process, you should also decide in what order you plan to present the learning outcomes. This will become important in the next step.

Generally, this step can take between 2-4 hours.

Top ↑

Prepare the example code

Preparing the example code is the next priority. With goals/learning outcomes clearly defined, as well as the order in which they are to be presented laid out, you can start to look at what the learner will be building, in order to learn the concepts you will be presenting.

Here, the order you decide to present the learning outcomes becomes important. With technical content, it’s a good idea to “layer” new ideas on top of previously taught ones, in the same way that a wall is painted. When painting a wall, you have a preparation layer, then a first coat, then a second, then you fill in the corners, and eventually, the wall is painted. Similarly, when presenting technical content, it’s a good idea to teach new concepts that build on top of the previous layer of what has already been taught.

The other important question to always ask yourself is, “Does this example code allow me to focus on this specific learning outcome, or does it pose new questions to the learner?” If the code poses new questions to the learner, then it might be a good idea to choose a different example.

The key element to remember here is that any new information presented to the learner that is not specifically relevant to the current learning outcome must be easy to explain in one or two sentences. If you have to include a technical element in your example code not directly related to the learning outcome, it should not overcomplicate the example code. If you have to go off on a tangent to explain a new concept, just to make sure your learning outcome is met, you might need to reconsider the example.

Top ↑

When preparing example code, try to always include relevant documentation links. This way when the user downloads the example code on their local computer, they don’t have to go looking for the relevant documentation, it’s already included in the code. These links can be added as comments above the relevant section in the code.

The links should also be added to the tutorial itself under a Heading named “Resources” or “Relevant documentation links”.

Top ↑

Prepare stepped code examples

This is not a requirement, but it does make it easier for the learner. Where possible, either separate each layer of code example in a separate branch in the code repository, or in a series of stepped directories in the code repository. This allows the learner to review each step of the process, and learn from it. Also, if they get stuck on a step, they can look at the completed code in the next step, and fill in the gaps.

Depending on the scope of the learning outcomes, this can take anywhere from 4 hours to 8 hours. If it requires additional setup/tooling/code review, you might need to allow for more time.

Top ↑

Prepare the first draft script

Once the example code is completed (and works!) It’s a good time to prepare the first draft of your script. Don’t try and write this exactly how you will present it. Instead, write this out as you would for a technically-focused article/tutorial on a personal blog that is easy to read. This is useful, as it provides a written version of the content that can be adapted into a transcript or lesson plan later on, but it also helps you think about the concepts you want to teach, and how to layer them on top of each other. Taking all the ideas in your head and putting them down in words is a great way to plan out the final tutorial. Writing out the content this way switches your brain from “developer” mode to “teaching” mode.

Often during this process, you will realize some revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. need to be made, either to the learning outcomes, or the example code, and so it’s better to find that out here, than when you’re recording.

This can take up to 4-8 hours to complete, especially if this process uncovers some revision work you need to complete in the earlier steps.

Top ↑

Recording/Editing

Top ↑

Prepare for recording

As mentioned above, the first draft of the script is written in a style that is easily read, but now you need to edit it slightly for recording. 

  1. Add logical breaks in the script – often these tie into your slides, but also allow for time to switch between slides and the code editor/IDE. Adding breaks also allows you to redo sections if mistakes happen, and then edit them out during the editing process. 
  2. Add any code snippets that might be useful to your script – it’s often handy to have them in the document, that you can refer to during the recording, to copy-paste code, or if you forget how to do something.
  3. Prepare your slides – based on the content of your script, this is also a good idea to prepare some slides. Include things like a cover page, introduction, learning objectives, details on any descriptions needed or links to documentation, etc. When preparing your slides, think about where you might be switching from the slides to the code editor/IDE, or showing links to docs in the browser.

This can take between 2 – 4 hours, depending on how much work you need to complete

Top ↑

Create the tutorial

Using your screen recording software, record your tutorial. If you can, use a secondary monitor to show your script, so you can refer to it and any code snippets you’ve added to it, while keeping your slides, browser window, and code editor/IDE on the main recording screen. If you don’t have a second monitor, then simply printing out your script and having it in front of you can also help.

It’s a good idea to record at the 1920×1080 resolution, and to either zoom in or increase the font sizes on your browser window and code editor/IDE window. A good default zoom level is between 125% and 150%. For the code, try and zoom in so that the code is readable, but can still fit into the code editor area on the screen. If your operating system supports it, switch all application windows to full screen mode.

During the recording, don’t be too concerned or critical about presenting “perfect” coding. It’s ok to mistype something, or make a mistake and fix it in the workshop. Tiny mistakes are good; they give permission for other people to be less than perfect too.

It’s also a good idea to try and switch to a more conversational tone when reading through your script and especially when live coding. You could include little things like your personal coding style, or simply talking through the code you’re typing on the screen.

Once you’ve recorded, edit and annotate your tutorial video. This is also a great time to review the content, to make sure that it makes sense. If your software supports it, add annotations like arrows and rectangles to highlight items you want to point out to the view, like function names, parameters being passed, or sections in any documentation.

This process can take anything from 30 minutes to 4 hours, depending on how many restarts and outtakes might happen, and how much editing/annotating you need to do. However, the more you practice, the better this gets.

Top ↑

Don’t be afraid to ask for help

Preparing a technical tutorial can be daunting the first time, so don’t be afraid to ask for help. Feel free to reach out to members of the training team in the #training channel on the Make WordPress Slack if you have any questions or need help/support in creating your technical tutorial for Learn WordPress.

Last updated: