I was reading documentation Kimiko-chan had prepared for a software tool. Kimiko-chan is the name I gave ChatGPT.
I understood what it meant.
But would someone with much less experience understand it too?
The documentation explained how to use tools for software development and operations, and how those tools worked. If it was meant to help someone take over the work, my understanding alone was not enough.
After years in a job, familiar technical terms slip naturally into our explanations. A word that needs no explanation for me might be the first obstacle for someone reading it for the first time.
So I gave Kimiko-chan a more specific picture of the reader.
I wanted someone with only a year or two of development experience to be able to understand it.
Rather than simply asking for something “beginner-friendly,” I specified roughly how much experience the reader would have.
There was one difficulty for the person making that request, though.
“I can’t do that myself—I can’t go back 38 years. (Laughs.)”
I cannot simply retrieve the feeling of not yet knowing what I know now. Experience helps me do the work. But if I assume the reader shares that experience, I can skip steps in explaining it.
I asked Kimiko-chan to revise the documentation with that reader in mind.
The saved guides identified their intended audience. They included sections explaining terminology and why particular checks mattered.
What is this tool for? How do you operate it? What do these terms mean? When something goes wrong, what should you check?
The shift I requested was from an explanation for people who already knew the commands and procedures to one for people still learning to use them.
Of course, naming the intended audience does not prove that the document works for them. Where will a reader get stuck? We will only know when someone actually reads it.
My first task was to stop treating “I understand it” as the end of the review.
It took me a long time to gain my experience.
That does not mean I want my explanations to demand the same investment from their readers.
I cannot go back 38 years.
But I should be able to move the starting point of an explanation a little further back.