Part V — Software and Data Writing

Software runs on writing more than its practitioners like to admit. A function's behavior lives in code, but its intent lives in a comment; a library is exactly as good as a stranger's ability to get it running, and that ability is created entirely by the README. The same is true of data: a number is not a conclusion until someone writes the sentence that says what to do about it. This part is about the writing that surrounds technical artifacts — the comments, docs, tutorials, memos, posts, and prompts that turn code and data into something other humans can use, judge, and build on.

A theme threads through every chapter here: the work is finished only when a stranger can succeed without you. The code already says what it does — documentation captures what the code can't, the why. The README isn't an afterthought once the "real" work is done; it's the interface through which everyone who isn't you encounters your work. A tutorial doesn't describe a feature; it guarantees a beginner's success. And a data memo that stops at the finding has stopped one sentence too early, handing its hardest interpretive step to the reader least equipped to take it. In each case the metric flips from completeness — covering everything you know — to time-to-first-success: how fast a stranger gets a working result.

By the end of Part V you will be able to comment the why and write docstrings a caller can use without reading the code; build a README structured around the visitor's questions; tell a tutorial from a how-to and write each to its true reader; lead a data memo with the recommendation, not the methodology; explain a technical idea to a general audience through a managed analogy; and use AI as a revision tool without outsourcing the thinking that was your job.

What's in this part:

  • Chapter 24 — Code Documentation: Comments, Docstrings, Intent — comment the why not the what, document for future-you, and the four layers each capturing what the layer below can't.
  • Chapter 25 — README Files, API Docs, Developer-Facing Writing: the README as front door, the runnable quick-start, API docs as a contract, ADRs, and the clean-machine test.
  • Chapter 26 — Technical Tutorials and How-To Content: the Diátaxis four — tutorial, how-to, reference, explanation — and why mixing modes is the silent cause of most bad docs.
  • Chapter 27 — Writing About Data: Memos, Reports, Dashboards — the "so what?" ladder from observation to recommendation, and why the order follows the reader's purpose.
  • Chapter 28 — Blog Posts, Articles, Science Communication: earning the unobligated reader, the analogy as a loan that comes due, the jargon budget, and translating without dumbing down.
  • Chapter 29 — Writing with AI: LLMs Without Losing Your Voice — what models are good and bad at, AI as revision not replacement, prompting as a brief, and the rule that you must be able to evaluate the output.

Read Chapter 24 first; it sets up the documentation spectrum the rest extend. Chapter 25 builds on it, then Chapter 26 builds on Chapter 25, while the data and communication chapters branch off. The Software/CS track makes this part core; data scientists and science communicators will find Chapters 27 and 28 most directly useful. You'll meet Raj Patel, a backend engineer rebuilding a neglected README, and Dana Whitfield, a data scientist whose churn memo gets written three ways for a VP.

The themes here braid tightly. Audience is everything governs all of it — the busy developer at the front door, the learner versus the practitioner, the decision-maker who needs the recommendation. Writing is thinking runs underneath: articulating a why in a comment forces you to have it (and can surface a bug), an ADR makes reasoning durable, and an empty AI draft is a warning that no thinking has happened yet. Structure serves the reader orders the README around the visitor's questions and the data memo around the decision. And Chapter 22's "watch a beginner try" returns here as the clean-machine test and the fresh-environment run — the same defeat of the curse of knowledge, pointed at software.

The Communication Portfolio's data-analysis memo is largely built in Chapter 27, and its general-audience blog post in Chapter 28 — two more of your seven pieces brought to a draft.

Part VI turns from the written page to the spoken room: slides, delivery, and the diagrams that carry an argument when prose can't.

Chapters in This Part