# Reading Docs for Developers as an FDE: write so the client team calls you less

> The book's running example is an API that translates dog barks, and it was not written for FDEs. But its table of contents covers exactly what you need to settle before you leave a project.

Original: https://fdetimes.net/en/books-courses/docs-for-developers-fde-reading-guide/

A serious book on technical documentation chooses as its running example Corg.ly, an API that translates dog barks. Behind the joke sits a question every FDE has to answer: can the client team run the system without you?

In the foreword, Kelsey Hightower writes that if developers are the superheroes of the software industry, then a lack of documentation is their kryptonite. Picture that kryptonite at a client site: a Slack message asking, "The token has expired. How do I rotate it again?"

You can ship on time and give a beautiful demo. But if every operational task requires a call to you, you have not handed anything over, and moving on to the next client will be hard. That is why this book is worth an FDE's time, even though it was not written for FDEs.

**Key point:** If the client has to call you to run the system, you are the missing documentation.

## Written for engineers, but not for client work

Jared Bhatti, Zachary Sarah Corleissen and their co-authors wrote the book with the aim, as they put it on the [official site](https://docsfordevelopers.com), of scaling their decades of technical writing experience to the people who need it most.

The Write the Docs podcast observed that the book is written specifically for developers and runs from analysing readers through drafting, editing and publishing.

The launch post on the book's site is dated 7 October 2021. The second printing adds what the authors call reflections and advice on using AI in the writing process, so if you are buying, choose that one.

The book's limit is its setting: it follows a software team launching a new product. The readers of a newly launched product are mostly strangers, while yours have names and job titles and sit one call away. That is an advantage, because you can test everything you write on real people straight away.

So the three ideas below start from the book's chapters, but carrying them over to a client site is work you must do yourself. The examples and measurements are suggestions for applying them, not procedures printed in the book.

## First idea: no document is written for "the client team"

The [table of contents](https://docsfordevelopers.com/table-of-contents/) opens with Chapter 1 on understanding your readers. For an FDE, this is also the place to start, because "the client team" is not one reader.

Imagine you are integrating an agent into a logistics company's warehouse system. The on-call engineer at 2am needs rollback steps, the analyst needs to know what each data field means, and the IT administrator needs to know how to rotate tokens and grant permissions. A 40-page README will disappoint all three.

Your first job on site is to write down three columns: who is reading, what they need to get done, and what situation they are in when they open the document. If you cannot fill them in, your discovery is still missing some questions.

## Second idea: count questions, but do not trust the number straight away

Chapter 8 covers gathering feedback and working it into documentation, and Chapter 9 covers measuring documentation quality. For an FDE, the cheapest source of feedback is already sitting in the Slack channel shared with the client.

Take a hypothetical example: over 2 weeks, the client team asks you 40 questions, and 26 of them concern three topics: token rotation, retry handling and schema changes.

So 65% of the support load comes from exactly three documentation pages that do not exist. Write those three pages, and if questions fall to 18 over the next 2 weeks, the total has dropped by 22, or 55%. That is a number to report, but it is not yet evidence.

The more familiar a client team becomes with a system, the less it asks, even if you never write another page. So split the number by topic: if the three documented topics fall from 26 to 4 while the others hold at 14, the documentation has probably worked.

If every topic falls together, the team may simply have got used to the work. And if a page exists but people still ask about it, check whether it sits in the right place and is written for the right reader before you write more.

Question counts are still not enough, because clients may be too shy to ask and then do the task wrong. Add a test: give the runbook to a client engineer who has never touched the system, sit in silence and note every point where they stall. Each time you blurt out an explanation, you have found a line missing from the document.

## Third idea: documents need a recipient, not just an author

Chapter 11 covers maintaining and deprecating documentation. For an FDE, this may be the hardest chapter to apply, because you will leave while the documents stay and age with every configuration change the client makes.

Before handoff day, make sure every document has the name of an owner on the client side and a next review date. Mark outdated pages clearly or remove them altogether, because a wrong runbook in the middle of the night is worse than no runbook.

Appendix A raises one more question: when to hire a technical writing specialist. It is worth taking to a client meeting as the body of documentation grows, because an FDE should not have to keep every page to the very end.

## In what order should you read it?

The book best suits engineers who write their own documentation but were never taught how, especially those facing their first handoff. If you are a long-serving technical writer, a book written for developers will probably offer less that is new. Do not read it in sequence like a textbook; read it to the rhythm of the project.

| Part of the book | When you need it on site | What the FDE should do |
|---|---|---|
| Chapter 1: understanding readers | First week, alongside discovery | Draw up a table of who reads, what they need to do and in what situation |
| Chapter 8: feedback | When the client team starts using the system alone | Collect questions from Slack and email into one list |
| Chapter 9: measuring quality | A few weeks before handoff | Set a baseline question count and run the unassisted test |
| Chapter 11: maintenance and deprecation | Before leaving the project | Assign owners and review dates |
| Appendix A: hiring specialists | When documentation outgrows the project team | Raise the question with the client |

Read the sections on drafting, editing and publishing when you sit down to write your first page. Read the second printing's AI advice at the same time, if you plan to use a model for drafting. Whatever tool you use, rerun every command yourself in the client's environment before handing anything over.

## Turning documentation into evidence on your CV

This skill is hard to demonstrate if a CV only says "good at writing documentation". A line such as "Wrote runbooks for the three most-asked topics: questions about them fell from 26 to 4 after 2 weeks, and a new engineer could follow them unassisted" carries far more weight, provided you measured the numbers yourself.

Without a real client, you can still write documentation for an open-source API, ask a friend to follow it and publish both the before and after versions.

When reading FDE job descriptions, watch for words such as handoff or enablement, then ask the recruiter who keeps the documentation up to date after the FDE leaves. If they cannot answer, the job will probably land on you.

The real test of a deployment does not happen while you are there. It happens the week after you leave, when someone at the client hits a problem and opens your document instead of Slack.

**Try this week:**

- Export the client team's questions from the past 2 weeks, sort them by topic and write documentation for the most-asked one.
- Ask an engineer who does not know the system to follow one of your runbooks, watch in silence and note every point where they stall.
- Add an owner line and a next review date to the top of every document you will hand over to the client.

## Sources

- [Docs for Developers (trang sách chính thức)](https://docsfordevelopers.com)

- [Table of Contents – Docs for Developers](https://docsfordevelopers.com/table-of-contents/)

- [WTD Episode 35: Docs for Developers book, with Jared Bhatti and Zachary Sarah Corleissen](https://podcast.writethedocs.org/2021/10/31/episode-35-docs-for-developers)