By Cherie Woo
“Here’s my technical spec—all you need to do is format it,” an engineer once told me. “Make it pretty,” she added.
When I began my API technical writing career, I always took such statements personally, as a sign of disrespect for my profession. I have a technical and programming background, and I definitely have the skills to do more than just “pretty up” docs. However, over the years I have learned to take a different perspective and not take these statements so personally. Exclusive attitudes from engineers come with the territory. The feeling of disrespect seems to stem from a natural effect of the engineers being the source of knowledge and the technical writers being the pursuant of that knowledge.
Being a successful technical writer is not just about pursuing and writing about technical knowledge, but about enabling and empowering users with the information we share with them. When my technical writing revolves around how to give the user a better experience with the API and documentation, even the principal engineers and senior development managers start paying attention to what I have to say. Having a career as a technical writer makes me proud.
Here are a few examples:
Using the API
Developers who expose an API don’t necessarily use it, especially not in external user scenarios. As I’m writing about an API, I often have to discover the details of the API myself. If I don’t have access to code, or if the developer has not entered any code comments, the best way to find out how parameters are used or how a method behaves if called a certain way is to use the API myself.
Not having access to code is sometimes a benefit. I can take on the role of an external user and come up with simple test scenarios that developers wouldn’t think of because they tend to make a lot of assumptions. During the process of using the API, I uncover bugs or come up with questions about the workflow and even suggestions on how to improve the user experience.
Developers appreciate this kind of feedback because they want to make the API more useful. Others on the team, such as quality assurance and product managers, also appreciate the increased testing coverage and usability improvements.
Writing Useful Examples
Our readers are more drawn to reading practical examples than to reading long text. Providing and validating examples add even more value to the benefits of using the API.
In addition, working with examples helps put the pieces of the puzzle together as the abstract technical concepts begin to click and make sense. This deeper understanding leads to a greater appreciation of what the developers have built.
When developers see how I truly appreciate their work and how I can go beyond editing their specs by providing my own examples, I make a connection with them. When this connection happens, communication becomes easier and facilitates better collaboration.
Asking Insightful Questions
While using the API and writing examples, sometimes something does not make sense. Pragmatic usage of the API helps formulate more insightful questions. The phrases “That’s a good question” and “I never thought about that” are always music to my ears.
If my question is about an existing technology I don’t know anything about, or if I run into some obscure error message, I go to Google before I go to our engineers. When they can tell that I’ve done my homework, they become more willing to offer me their time.
As for the aforementioned engineer who told me to simply format her technical spec—asking insightful and well-researched questions helped improve our relationship. She didn’t get a prettied up doc from me, at least not immediately. Instead, I sent back her (unformatted) spec with lots of embedded questions and comments.
I didn’t let her “make it pretty” request get to me. Instead I spent a lot of time digesting her technical spec and understanding how the technical information translated to practical usage. I sent her the marked-up spec along with an invite to a half-hour Q&A session.
At the meeting, she appreciated all my questions as I went through them, and gladly answered them. When I got to a question about a possible error condition, she answered, “It doesn’t matter” with a bit of attitude. I pointed out that the error message stated an “internal server error” instead of giving me a more meaningful message. She was surprised that I had tried to use the API, and then admitted that there should have been better error-handling and a better error message.
After the meeting, she asked me to review a list of error messages, which was an indication that she had gained confidence in my ability to do something beyond just formatting her spec. Overall, it was a very collaborative and productive session (lasting two hours!).
Catching Inconsistencies
As a technical writer, I’m at the frontline for catching inconsistencies because I am exposed to and write about the many different areas of the API. Since multiple developers can work on the same code over time and on different areas at the same time, user interfaces can easily become inconsistent.
This happens not just with functionality but even in seemingly simple things like API element names. With an API, the element names are the UI, so consistent naming becomes very important. Developers appreciate it when inconsistencies are brought to their attention, especially when I come prepared to help with defining naming conventions.
As you can see from the previous examples, they are nothing but typical tasks that a technical writer would do as part of delivering documentation: using the product, providing examples, understanding concepts, and catching errors.
The point I want to highlight is that technical writers do not have to go through great lengths to solicit respect. We do, however, need to roll up our sleeves and flex our muscles to do our jobs well just like any other team contributor. And when we do, we bring tremendous value to the table.
Developers and engineers need technical writers to equip the users with the understanding of their software. The engineers start showing respect and appreciation when they see how we can represent a customer user’s perspective.
Don’t let “make it pretty” situations turn into “the engineers versus tech writers,” or “them vs. us.” Instead, recognize that “them + us = we.” Together we help the user. When we keep in mind that engineers and technical writers are all on the same team working toward the success of the product, a make-it-pretty request really translates to a make-it-user-friendly challenge.
Cherie Woo is currently an API technical writer at Accela Inc. Cherie started her career in programming and has worn different hats at software development shops around the San Francisco Bay Area. While doing application development at McCue Systems Inc., a lunch-break internship at a graphic design studio tapped into her artistic side and rounded off the technical edges. She eventually decided to transition out of programming into technical training, and finally into technical writing when she was recruited as a programmer writer at MDL Information Systems Inc., which is now Accelrys Inc. (no affiliation with Accela). Between Accelrys and Accela, she had a stint at Safeway Inc.’s IT architecture and design group, which gave her valuable insight on customer experience with technical documentation.
