I’m starting out on a new role. Still a technical writer, still at the same company, but on a new product, working with a new group of people and a new set of docs. Here are some of my thoughts on getting started in a complex new field.
I’m reading everything I can about my new field, and watching the videos that’ll help me figure out what it’s about. As a technical writer, I’ll soon be immersed in both the technical and the theoretical side of the field. But before that immersion happens, it’s good to find out how people out there in the world are using the technology. The applications where they’re putting it to use. The functions they expect it to perform.
In my case, the new field is machine learning. That’s a big change from my previous role, documenting maps APIs. I loved working on the maps APIs, and now I’m super excited to learn something new.
Noting the new concepts and terminology
As I read articles and watch videos, I’m making notes of the things that puzzle me or are new to me: concepts, terms, methodologies, technologies. These notes may become part of the docs I write, or they may turn out to be useful only to me. They’re valuable, because I’m currently acting as a first-time reader in the field. Later I’ll forget what I didn’t know. It’ll be harder to put myself in a newbie’s shoes.
For example, watching this video about machine learning, I found I needed a new definition of the term “vector”. The video used the term in a way that was unfamiliar to me. I found some help on Stack Overflow. (It turns out that, in simple terms, a vector in machine learning is a series of values, which you can think of as a row in a table.) I made a note of the term and its meaning, in case I decide to add a glossary in the docs.
Discovering the audience
At this time, I didn’t have a good feel for the intended audience. Perhaps the intended audience for the documentation would already know the term that I hadn’t understood. But it did no harm to make a note. In fact, it helped solidify my own understanding of the term.
While reading, I’m looking to get a feel for the various types of audience in the field. This will help me narrow down the audience for the docs. What types of experts are there out in the world? In the case of machine learning, there’s a diverse audience, all the way from machine learning scientists who design the training/inference models, through data scientists who know all about data and want to try machine learning as a new way of gaining insights from the data, and application programmers who don’t know anything about machine learning and just want to use a specific application of it in their app.
Figuring out the workflow
When I first started learning the field, I didn’t look at my own organisation’s existing docs for this range of products. Instead, I immersed myself in what the world out there is doing. What’s the typical workflow that people are talking about and trying to implement? Later, I’ll look at how our own products fit into that workflow, and how our docs explain the flow.
Remembering that things change fast in technology
If you’re moving to a new project with an existing doc set, take into account that things were probably different when the doc set was created. Perhaps the audience has moved on since the early days in that particular field. Perhaps most of your readers now know more about the topic than they did when the docs were written. This is particularly relevant if the technology was new when the docs were written.
Perhaps the readers are using a different set of terminology now. People may have standardised on terms, while it’s possible the docs have not kept up.
As a new reader of the docs and a new entrant into the field, you’re in the best position to notice this kind of thing.
Something I learned while writing this post: newbie versus nooby
There’s a difference between a nooby and a newbie. I didn’t know that. I thought it was just a spelling difference. In fact, there are three terms: noob (or n00b), nooby, and newbie. A noob is a rather naive, some would say even stupid, person. This term is used particulary in the world of games. Nooby is an adjective referring to the type of (silly/annoying) thing a noob would do. A newbie is someone who is new to the field or area under discussion. It seems you don’t really want to be called a noob, whereas being a newbie is not a bad thing. At least newbies can spell!