How to Write Documentation That Solves User Problems | James Beach

Gowri: Good day, everyone. Welcome to the Knowledge Base Ninjas podcast. What a great guest to have: James Beach, freelance consultant in technical writing and business analyst at An Idea Smith. James, welcome to the podcast. It’s over 30 years, or close to 30 years, of experience in this field. A lot more memory lanes to travel, I guess. But before we start anything, just talk a little bit about yourself how did you land in this amazing journey, and what’s keeping you busy these days?

James: Sure, and thanks for having me. Glad to be on the podcast. My journey may be typical for many. As I graduated from college, I graduated with an English degree and most of a major in art, and I was also interested in tech. And so, like many people on graduation, I wasn’t sure what direction I wanted to go in. A friend of mine had said, “Well, you know, you work with text, you work with visual art, and you work with tech how about website design?” And I thought that was a very good match; I put it together.

So I worked in web design for a bit this is somewhat early days of the internet, not the earliest. This was around 1996, and I had gotten into developing and scriptwriting, as in CGI scripts back when that meant Common Gateway Interface, and before it meant computer graphics imaging. So those are the Perl days, when Perl was up and coming, which is a dinosaur language now. I did that for a bit.

And then I realized that what I really enjoyed about the tech field was actually understanding the concepts and then explaining them to others. It was a fun challenge, and it felt conversational, and it had me in a place where I was continuing to learn. It also had me out of always needing to be in the details it would frustrate me that I could be writing a script that was thousands of lines long, and it wouldn’t work because there was a semicolon out of place that I would then have to hunt down.

That was that journey, and that’s what led me to technical writing. And here I am.

Gowri: Right, amazing.

Gowri: Some of the names I’m just going to call out with you’ve written for Amazon, Sony, Microsoft, DreamWorks very different audiences. I mean, it all resonates from your background; I can see. But what’s the first thing you try to find out about the reader before you even start writing anything?

James: Well, with technical writing in particular, I like to really understand the user being the writer. So I’ll try to have a persona in mind. I’ll create a persona of the user, and that will depend also on discussions with the development team and product managers or owners if I’m at a company. Working at a company that’s so small that they don’t have a dedicated project manager yet- which has happened- but I’ll try to find out: who are they trying to target? Who is their core audience user? And I’ll try to create a persona for probably the biggest target of that audience.

And then, within that persona, I’ll figure out what a common use case is that would lead me through what they want to document about the product. And then, at that point, I will go through that product as if I were that user. I will have my specific computer set up, I will see about installing the product, and I will just start trying to use it through that use case. And I will be looking at the documentation if it already exists and if it doesn’t exist yet, then I will be making the documentation, both based on my journey from there.

That will lead me through a lot of territory, and it will, a fair amount of the time, lead me through things that have not been developed yet, and maybe have not even been considered yet by the development team which will provide me a good opportunity for feedback. I can say, “You know, this screen is really pretty confusing,” or “Do you really want this feature to work this way?” And respectfully, of course, only bringing up changes when I think it will be pretty impactful. So that will be the overall start of the process for me, and what will lead me through it.

Gowri: Most technical writers say they write for the reader, but in practice, what does that actually look like on a weekday afternoon when you’re deep in a doc? You did mention that you look at the persona, but is that exactly what goes in your mind when you start writing the documentation?

James: Well, for sure I’ll say, like, writing for the reader, to me, I think there’s overlap. But I do like to think of it as writing for the user, which puts the emphasis on helping the user. So, in very specific terms, when I’m writing for the user, I do keep in mind that I’m writing for someone who is probably already angry because they’ve had to check the documentation because something hasn’t worked which is usually when people read the documentation- a lot of the time. And I’ve found myself doing this myself I know that I should read the manual first, but I don’t want to, and I shouldn’t need to. So I will try to get as far as I can, and then see where I have to read the documentation. And so I’m already frustrated by the time I turn to the documentation, a lot of the time.

So I want to write for that mindset. I want to be speaking to the most likely issues that they want to solve first. I want to put that as the most findable thing. I want to address that in the first paragraph if possible, or in the outline, if possible, provide people relief for that, or at least offer them hope and a way, and show a clear path towards some of the problems that they might want to resolve first, before going to the other information. So that’s the main overall approach that I apply.

Gowri: It really shows that you understood this space very well, and particularly your intention to keep the readers happy and the mindset in which they come from. Amazing.

Gowri: And, yeah, we know that you write fiction, and you’ve also done stand-up. But as we got introduced, I also happen to know that you’re into music as well so many things happening, James! But have you ever felt that storytelling changed how you approach a user manual, or are they two completely different skills?

James: I would say it’s the same thing applied differently, so they’re related skills. Storytelling, to a certain extent, can be helpful within documentation. And understanding a user’s path is understanding a narrative. So creating a narrative like, literally, with a character, in this case called a persona, like we’ve been discussing. So narrative is involved, but the narrative is on the writer’s part we’re not necessarily surfacing that. We can, where it’s useful, but that’s where it starts for me: creating a narrative, which is basically a cause-effect relationship that makes sense at a higher level. Creating that first, and then applying it.

So storytelling applies in some specific and very useful areas of technical writing, such as troubleshooting, which is pretty straightforward, but you want to understand the path that the user has found themselves on, which is storytelling, and you want to provide them the goal at the end of their path. And there too, you can see some useful points for a distinction in that view: there can be what the user thinks they want, and there is what will actually help the user, which can be separate. So that’s one way that narrative thinking can apply.

Another similar situation would be if you’re creating a walkthrough for somebody you’re, again, creating a narrative there. Like, this is the path from most likely opening the software product, if it’s a software product, to completion of their task whether it could be setting it up, whether it could be going through a specific set of actions. So that is understanding narrative in that sense. But there’s a lot to narrative that will help inform your thinking for technical writing; that’s probably the best way to say it.

Gowri: Have you ever encountered a scenario where teams go completely wrong on this, or get this idea completely wrong?

James: Oh no, never, never. That’s a joke, yeah, so many times.

And technical writing, like a lot of development in general, offers a useful framing for that. It’s when you find something wrong; it is discovery, and it is a genuine opportunity to learn and grow. And I think that is useful for ourselves in life, even in a spiritual sense, but also good to experience on a regular basis in your job, in whatever your profession is. It’s healthy for the personality and the ego, and it is also healthy for growth.

So dealing with that can be difficult, and you want to not deal with it in a framework of shame, of having shame about it, which I think is an easy thing for us human beings to fall into. You will be wrong. We will all be wrong in tech especially; we will be wrong constantly. And so it is just important to take it more along the lines of: this was incorrect, what happens next, how do we address this, how do I address this, what was I wrong about and just incorporate that into the next stage, and then get to the level where things work.

Gowri: I think we partially spoke about this, but would you be able to let’s say I’m handed a product I don’t understand, and it’s for users I’ve never met can you walk me through how you would get into their shoes from a cold start? It’s an unknown user persona.

James: Yeah, which to some extent will happen all the time if you’re in tech; you’re documenting new things. There will be some new aspect of this for the audience, or the company would not be making it as a product or creating new features. So it’s a similar persona process, which I’ve found pretty useful: create an image of the likely users that they want to sell to, or that they’re currently selling to, that they want to shift, or similar. And then create a specific use case.

To get a bit more into the details of it, I like the use case to be as specific as possible, and it helps if it’s something that I’m somewhat interested in also. So let’s say, for example, someone was making an app that would create generated songs for postcards it probably already exists anyway. Who would want this? Well, I would want this as something to send to my relatives. So that means I would want certain aspects to it, and I’d want to be reassured about certain aspects to it. And then consider it from there, like, how would I create something from this to send to my uncle that he might enjoy for Christmas? And so now that is the very specific use case that I’ll walk through and try to use the product for, in a way that’s relevant to me that also ties me to the user.

Gowri: Yeah, great.

Gowri: That leads me to the Rapid Fire round questions: any documentation-related resources you can share with us? I’m sure you might have plenty, but something that always is close to your heart?

James: I’ll say, as our field, and all fields, is being affected by AI and tech, I think not enough people are trying different AIs on their own, and I can see both sides of that. Basically, most people seem to go into two camps, where they get either really familiar with ChatGPT or really familiar with Claude. And I think both of those are fine and improving, and it makes a certain sense to have your own process and workflow be based in one of those two different AI ecosystems, you could call them now, because there’s new tools all the time coming out.

But I think people also need to check out some of the other ones, even if they don’t end up using them at all. I would also suggest people use Perplexity, which I don’t think people have used enough of it’s very good for research. And if possible, they should also get familiar with open-source models and Chinese models, and use them cheaply through either Hugging Face or OpenRouter or similar. Just get familiar, because they have different ways that they react in terms of technical writing, they give you different output, and they edit differently based on your input. So that’s the landscape for that. As a long answer to a short question.

Gowri: That’s fine I’m expecting another short answer! Very, very short answer: what’s that one word that comes to your mind when you hear the word “documentation”?

James: Pain.

Gowri: You explained this already!

James: Yeah, but just to give another, basically, people turn to documentation when they’re in pain, 99% of the time. The only time they go to it first is because they have a memory of pain and not doing that. So proper documentation helps alleviate pain.

Gowri: Absolutely. My last question for the day to you is what’s one piece of advice you would give to your 20-year-old self?

James: This is teamwork and your manager, or your owner, whoever you’re working for, is part of your team. So watch them, and see how your interaction with them is on a personal level, because that’s the hardest times that I’ve had in my career have been with managers, whether it’s just a genuine mismatch. And that’s not only your quality of life experience, but that also shows how working for the company is likely to go. So keep a special eye on that.

Gowri: Yeah, absolutely, I think we always have this spoken about. People don’t leave; people leave because of people.

James: Yes, because of the job.

Gowri: Yes people are the solution and the problem.

Gowri: Great. I hope I have done justice to your experience. James, is there anything else you would like to add on top of what we spoke about already?

James: Yeah, basically your job is all of a piece with your life. So understand that the life skills that you have, and are developing, do apply to your professional experience, in all the positive ways. It all informs you it’s all a holistic universe within you.

Gowri: Very nicely said. I’m so happy to have you as my guest for this podcast, James, and the only thing I can do now is wish you all the very best for your future projects and many more successes to come.

James: Thank you. Thank you very much. It’s been a pleasure talking with you.

Gowri: Thank you, James. Take care.