READMEs, comments, commit messages, PR descriptions, design notes, diagrams, runbooks, incident reports, and replies to support requests. Over 20 lessons, you'll learn to write the things engineers write every day, starting from what the reader needs to do next. Every good example is quoted from the README, docs/, and .github/ of a real service (this site, 4peiron.dev); only the bad examples were written for the course.
The 20 lessons are split into 5 chapters. We recommend going in order from chapter 1, but feel free to dip into just the parts that interest you. Note: the good examples are real files from this site's (4peiron.dev) repository. All git and Markdown output was produced by actually running the commands; they can't run in the browser, so try them in your own terminal. The Python that measures text and the SVG diagrams can be run right on the page.
When you get stuck writing, the cause is almost never how you write; it's that you haven't decided who the reader is. You'll decide the reader, the goal, and the success criteria first, write in short words that can be checked, and build structure with Markdown.
READMEs, comments, commit messages, Pull Request descriptions, and Issues. You'll learn to write the text that sits next to code by comparing it with real files from this site's own repository. Finally, you'll build a bug report starting from the steps to reproduce.
Design notes written before implementation, decision records that include the options you didn't pick, diagrams, and how to write about "what this can't do." You'll write text that lets someone reading it six months later reach the same decision. Finally, you'll write a section that states limits and assumptions up front.
Runbooks that are done once you follow them, "When things go wrong" sections that readers can search by symptom, incident reports, and replies to support requests. This chapter covers writing for readers who are in a hurry.
Left alone, what you write turns into a lie. We wrap up with ways to find outdated docs automatically and how to give feedback on other people's writing. Finally, you'll build a review checklist covering all 20 lessons.
Once you've finished all 20 lessons, move on to Git & GitHub for Beginners to keep your writing in version history, or How Software Projects Run, which treats requirements and design documents as part of the process. To make the code itself readable, try Intro to Design & Refactoring. A membership unlocks every course.