Writing Tutorials for Learning  ## Metadata - Author: [[Julia Florczak]] - Full Title: Writing Tutorials for Learning - Category: #articles - Document Note: --- tags: - #developer-education - #tutorial-design - #learning-science Author: Julia Florczak Source: Article Reference: https://meduet.dev/learn/writing-tutorials-for-learning date created: 2025-08-22 00:00 --- # Title: Writing Tutorials for Learning ## Table of Contents: - [📚 Overview: Learning over problem-solving](#-overview-learning-over-problem-solving) - [🗺️ Mapping the learner’s journey](#-mapping-the-learner’s-journey) - [🎯 Learning objectives](#-learning-objectives) - [✅ Prerequisites and “Before you begin”](#-prerequisites-and-before-you-begin) - [🛠️ Learning by doing](#-learning-by-doing) - [🧭 Guided steps: Tell them what/ how/ what they did](#-guided-steps-tell-them-what-how-what-they-did) - [🚀 Example: Deploy the application](#-example-deploy-the-application) - [➡️ Providing next steps](#-providing-next-steps) - [🧾 Summary](#-summary) - [📖 References](#-references) - [🗒️ Notes](#-notes) - [🗣️ Paraphrase](#-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical validity](#-logical-validity) - [🔍 DARVO Analysis](#-darvo-analysis) - [🔍 SEO Evaluation](#-seo-evaluation) - [🎯 Conclusion](#-conclusion) ### References: - Primary source: https://meduet.dev/learn/writing-tutorials-for-learning ## 📝 Summary: The article argues that effective developer tutorials prioritize learning over immediate problem-solving. It recommends structuring tutorials around clear learning objectives, explicit prerequisites, and a hands-on, step-by-step approach that guides learners to perform tasks, understand their actions and outcomes, and build confidence. The core instructional loop—tell them what to do, how to do it, and what they did—anchors cognitive feedback and reflection. Tutorials should simulate realistic use-cases, avoid “toy” endpoints as final goals, and conclude with next steps and resources to deepen skill development. ## 📖 Main Content: The author reframes tutorials as learning experiences rather than troubleshooting guides. A learner-centric map starts with goals and starting knowledge (prerequisites), then proceeds via active practice—building with the product in a realistic context. The tutorial writer reduces cognitive load by chunking tasks, using numbered instructions, and aligning detail to learner level. After each task, the writer explains outcomes, addresses likely pitfalls, and celebrates progress to reinforce self-efficacy. The piece closes by advocating for pathing to further learning. - Key quotes: - “It’s to learn.” - “To guide the learner through the tutorial, repeat the following steps: 1) Tell them what to do 2) Tell them how to do it 3) Tell them what they did.” - “Avoid having the learner build nonsense applications.” Personal reflection: - This aligns with experiential learning and cognitive apprenticeship: modeling, scaffolding, and reflection. The “what/how/what happened” loop is a practical instantiation of feedback cycles that strengthen transfer to real projects. The emphasis on prerequisites and context reduces intimidation and dropout risk—vital for developer advocacy materials where heterogeneous skill levels are common. ### 🗒️ Notes - 📚 Learning over problem-solving - Tutorials are for acquiring skills, not immediate fixes. - Beginners need conceptual coverage across topics to grasp the product. - 🗺️ Learner journey and navigation - Define destination (objectives) and starting point (prerequisites). - Use objectives as a contract to set expectations. - 🎯 Learning objectives - Example objectives: “Create a product using the Foo.js client library,” “Deploy to Foo Cloud.” - Objectives guide design and help learners self-select. - ✅ Prerequisites / Before you begin - Specify tools and baseline knowledge (e.g., Git, account, JS basics). - Helps learners assess fit and prepare environment. - 🛠️ Learning by doing - Prioritize active engagement over passive reading. - Use realistic tasks; avoid “Hello, world!” as the final goal. - Context mirrors intended use to enhance transfer. - 🧭 Guided steps (scaffolding) - Break challenges into smaller tasks with escalating complexity. - Use clear instructions, numbered lists, screenshots/code as needed. - Align instruction fidelity to learner level (novice vs. experienced). - 🔁 Instructional loop - Tell them what to do (framed as a meaningful problem). - Tell them how to do it (clear, concise, stepwise instructions). - Tell them what they did (outcome explanation, reflection, troubleshooting, celebration). - 🚀 Example: Deployment flow - Commands: “foojs publish” → deploy; “foojs open” → launch app. - Explain results: app deployed to default region, public URL. - ➡️ Next steps - Encourage iteration on the working app. - Provide resources for advanced features and deeper learning. ## 📖 References: - Florczak, Julia. Writing Tutorials for Learning. https://meduet.dev/learn/writing-tutorials-for-learning ## 🗣️ Paraphrase: 1) Original idea: The point of a tutorial isn’t to solve a specific problem; it’s to learn. - Paraphrase: Tutorials exist to build capability, not to patch a one-off issue. While readers may hope to apply skills later, a good tutorial focuses on developing understanding and fluency first. 2) Original idea: Repeat the loop—tell them what to do, how to do it, and what they did. - Paraphrase: Structure each step as a mini-cycle: define the task, walk through the procedure, then connect actions to outcomes so learners can see cause and effect and consolidate knowledge. ## 📰 Newsletter: This week in WordPress and open source learning: If you’ve ever wondered why some tutorials leave you pumped and shipping, while others leave you lost in tabs, it comes down to learning design. We dug into an excellent piece on crafting tutorials that teach first and troubleshoot second—set clear objectives, state prerequisites, and guide with a tight loop: what to do, how to do it, and what you just accomplished. Try adopting this in your next dev doc or workshop. Updates: WP core progresses on performance fixes in block rendering and theme.json parsing; keep an eye on upcoming 6.x discussions for developer notes. New plugins on our radar: a lightweight asset loader for conditional scripts, and a block-pattern organizer for design systems. Community highlights: contributor onboarding cohorts are opening next month—great for first-time contributors who want hands-on mentorship. Resources worth a click: - Learning design for devs: the what/how/why loop that sticks - Core performance field notes and call for testing As always, build, break, learn—and tell us what you shipped. We might feature it next week. ## ✅ Action Items: Prompt to align future articles with your advocacy, contributor engagement, and OSPO goals: - For each article, answer: - How does this piece advance open-source education in WordPress (e.g., clearer onboarding docs, improved tutorial design, contributor skill-building)? - Which contributor journey stage does it support (awareness, onboarding, first PR, sustained contribution, maintainer growth)? - How can insights be translated into GoDaddy DevRel programs or workshops (curriculum design, office hours, contributor sprints)? - What transparency and inclusivity practices does it model (explicit prerequisites, accessible language, DEIB-conscious examples)? - How could an OSPO adopt this (governance playbooks, contributor ladders, documentation standards, tutorial templates)? - What metrics would validate impact (tutorial completion, first-time contributor retention, time-to-first-PR, docs NPS)? - What artifacts will we produce (tutorial template, checklist, contributor guide, funding rationale for docs/education)? - For this article specifically: - Create a WordPress tutorial template using the “what/how/what happened” loop. - Summary: Well-crafted tutorials leave the learner feeling empowered and hungry for more, but they also risk making potential users lose interest in your product if not done well. Keep reading to learn the foundation of tutorials that propel your visitors into becoming users. - URL: https://meduet.dev/learn/writing-tutorials-for-learning #### Learning over problem-solving A tutorial is a lesson that teaches someone how to use your product effectively. Tutorials turn people with little to no prior knowledge or experience of your product into users. But while most of us pursue new skills in the hopes of putting them into practice one day, the purpose of a tutorial isn’t to solve a specific problem. It’s to *learn*. A tutorial may briefly touch on several topics to give the learner a basic understanding of a product or technology. It may not be what an experienced user would do, but instead simplified to make sense to a newcomer. #### Mapping out the learner’s journey  Imagine that you’re drawing a map for someone. Before you can help them navigate, you first need to know where they want to go, and where they’re coming from. Only then can you determine the best way for them to get there. ##### Learning objectives The destination, or the *learning objectives*, is the skills the learner gains by completing your tutorial. As a result, the quality of your tutorial depends on how efficiently the reader gains those skills, and how well they retain them. Example: Learning objectives By the end of this tutorial, you’ll be able to: * Create a product using the Foo.js client library. * Deploy a Foo.js app to Foo Cloud. Learning objectives are mainly a tool to help you design your tutorial. But they can also serve as a promise to the reader—if they complete your tutorial, they’ll walk away with these skills. By setting expectations early, they can determine whether this is the right tutorial for them. ##### Prerequisites Even if we know where they want to go, the most efficient way to get there depends on where they are right now. Are they a junior developer? Have they used any of your other products before? Do they have experience with TypeScript? To determine the best way to teach anyone, we need to understand what they already know. Unfortunately, individually assessing every learner at the start of the tutorial may not be feasible. But we can let them know whether the tutorial will be relevant to them, by listing the skills or tools we expect them to have before they begin. For example, does the tutorial require specific tools or basic understanding of a related technology? #### Before you begin To complete this tutorial, you’ll need: * Git installed on your local machine. * A Foo Cloud account. * Basic experience in JavaScript. There, you’ve helped the learner figure out the skills they’ll have gained by the end of the tutorial, and whether it’s relevant to their current skill set. The next step is to figure out the most efficient way to best get them there. #### Learning by doing  Photo by [Richard Sagredo](https://unsplash.com/@sagredophotography?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/photos/oDlLU_1hZwM?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) It’s tempting to think that the best way to teach someone, is to explain it to them. It turns out, rather than passively reading or listening to someone, we learn things better by actively engaging with the material—for example by actually performing the skill ourselves. We learn by making sense of things that happen to us and then adjusting our actions for a more desired outcome. By merely reading a text or listening to someone speak, we miss out on the feedback loop between what we did and what happened—and consequently, the opportunity to make a connection between the two. If you want to learn how to play tennis, you’ll likely have more success by heading to a court and picking up a racquet instead of a book. After each ball you hit, you reposition yourself and try to hit the ball differently. Even better if you have an instructor with you to help you make sense of what you’re experiencing. In other words, the best way to teach someone how to use your API, is to have them actually use it to build something themselves. Ideally, what they build should mimic the context in which they intend to apply what they learn. Avoid having the learner build nonsense applications. While printing “Hello, world!” can be a step in your tutorial, it shouldn’t be the final goal. Instead, picture how they’ll be using your API and aim to replicate a real-life scenario. Ok, but hang on. If the best way for someone to learn is for them to do it themselves, how do you get someone to do something they’ve never done before? That’s where you come in. #### Guiding the learner step by step Being challenged to build an application using an API you just learned about can be scary for a new learner, who likely wouldn’t even know where to begin. Break down the problem into smaller, more manageable challenges, each building on the skills or knowledge that the learner gained when solving the previous one. This lets the learner practice what they just learned. For each challenge, the learner performs a series of actions to solve problems. They may need to sign up for an account, create an API key, install a client library, and then call the right functions. While they might be able to figure it out themselves by experimenting, by showing them how, through clear instructions, you’ll make better use of their time. Guide them towards their goal by shining a light on what to do next. Each set of actions the learner performs should have a meaningful outcome. But the learner might not understand the consequences of what they did. Your job as a teacher is to help the learner connect the dots. Which actions led to what results? To guide the learner through the tutorial, repeat the following steps: 1. **Tell them what to do** 2. **Tell them how to do it** 3. **Tell them what they did** #### Deploy the application It’s time to share your app with the world. In this step, you’ll deploy your application to Foo Cloud using the `foojs` command-line tool. 1. In your terminal, run the following command to start deploying. This may take a few minutes depending on your internet connection. ``` foojs publish ``` 2. Open the app in your browser. ``` foojs open ``` Foo.js built your app and deployed it to your default region. Your app is available on `https://*.foo.cloud`. ##### Tell them what to do Start by giving the reader a problem to solve. Feel free to use storytelling to explain why this is a problem worth solving. Try to find a balance between making it both exciting and challenging. > It’s time to share your app with the world. In this step, you’ll deploy your application to Foo Cloud using the `foojs` command-line tool. > > Keep in mind that you’re asking the reader to do something that’s new to them. By introducing too many new terms and concepts, you risk intimidating the learner. They might think they skipped a step, or second-guess whether it’s the right level for them. ##### Tell them how to do it Provide instructions using clear and concise language that is easy to understand. > 1. In your terminal, run the following command to start deploying. This may take a few minutes depending on your internet connection. > > > > ``` > foojs publish > ``` > If the learner needs to perform multiple actions, consider using numbered lists to allow the reader to check them off and to keep track of where they are. If you’re switching between the browser and the code editor, it can be hard to keep track of your progress when all the instructions are hidden in a long paragraph. Note that the amount and the type of instruction a learner needs depends on their previous experience. Experienced learners might instead only need a code snippet or a screenshot to understand what to do next. Make sure to match the type of instruction with the level of the learner. ##### Tell them what they did > Foo.js built your app and deployed it to your default region. Your app is now publicly available on `https://your-app-name.foo.cloud`. > > After the learner has completed all the actions, they should’ve completed what you outlined earlier. By going through the motions themselves, they’re already building practical experience with your product. Give the learner a chance to reflect on what they did, and what happened as a result. * **Help them understand what they did.** Since they might not understand the consequences of their actions, you need to show them the connection between what they did and what happened. For example, “When you ran the `INSERT` query, FooSQL added a new row to the table.” * **Address potential issues or questions.** In a classroom, the student can ask the teacher for help when they get stuck. Since you’re not there to help, try to address any issues that may prevent them from progressing. * **Celebrate that they’ve successfully completed the task you asked them to do.** The feeling of doing something by yourself is empowering. Even if they merely followed instructions, they accomplished something—hard proof that they can successfully use your product to create something meaningful. #### Providing the next steps By the end, the learner should have achieved the learning objectives at the beginning of the tutorial. After completing your tutorial, they’ll likely have new questions based on what they did (or didn’t do). They’re now able to ask more complex questions and maybe even find information on their own. At this point, the learner has a working application that uses your API that they can continue to tweak and experiment with, or ideally even use as a base for their own project. While they might not be ready to take on another tutorial yet, they may eventually want to improve upon what they built. Provide additional resources that let the learner progress and learn about new features they can use. #### Summary This article has outlined a foundation for making tutorials aimed at developers. By integrating learning science into your developer content, you can improve both engagement from your readers, and how much they retain from it. I encourage you to adapt the tips and examples to make it relevant to your audience and your company voice. Stay tuned for more resources that will help you create better educational content for developers., Writing Tutorials for Learning, Julia Florczak, 01h4cvznv4g2went65g0wenmej.