Answering questions in James Gill's upcoming book, How to Get Started as a Technical Writer

by Tom Johnson on Feb 21, 2016
categories: beginners

• My Tech writer “day in the life” contribution
• What is your current title?
• How long have you been a technical writer?
• What are the companies you’ve worked for like?
• What was your first technical writing job, and how did you find it?
• What does a “typical” work day for you look like? Feel free to describe with as much detail as you’d like.
• What does technical writing look like in the next 5-10 years? How might a person just starting out prepare for such a future?
• What do you like best about technical writing? What do you like least?
• What is the most difficult part of being a technical writer?
• 9. If a person seeking their first technical writing job wanted to get hired onto your team, what are the three most important things you’d tell them to do?
• 10. If you could give only one piece of advice to your younger self just starting out in technical writing, what would it be?

My Tech writer “day in the life” contribution

James Gill invited me to contribute responses to a questionnaire about a typical day in the life in my career for the upcoming second edition of his book, How to Get Started As a Technical Writer. This section will appear in a chapter that discusses the real-world work life of technical writers in different industries and specializations.

James is expecting to publish this second edition book in the next month. On the book details page, you can sign up to be notified when it’s available. As a way to help promote the book and build excitement for its upcoming release, James allowed me to publish my questionnaire here.

You can view more details about the book here: How to Get Started As a Technical Writer

Here are my responses to the questionnaire:

What is your current title?

Senior technical writer

How long have you been a technical writer?

About 11 years.

What are the companies you’ve worked for like?

As a technical writer, I have always worked in companies that develop software. The companies vary in size and their culture, but mostly the innovation originates with the engineering group, and that’s where I tend to both interact and get the information I need for documentation.

Some companies in the Bay area provide free food and try to promote a fun, casual atmosphere. For example, when you interview for a tech job in Silicon Valley, you would almost never wear a tie. At some companies, engineers are champions at ping pong and foosball.

I tend to prefer smaller groups (like startups) where I have more autonomy and feel I can make an impact. However, startup environments can be somewhat of a roller coaster ride with hiring and layoffs (which depend on funding and sales), so at times I prefer the stability of an established company.

What was your first technical writing job, and how did you find it?

My first technical writing job was with a financial firm (Raymond James) in Florida, working with a team of about a dozen writers. I found the job through a recruiting agency that was trying to fill the position. At the encouragement of a colleague, I was attempting to transition from a job as a copywriter into technical writing.

To persuade the hiring manager that I had the technical skills required for the role, I learned RoboHelp and put together some sample projects. I also compiled my best copywriting samples into a portfolio.

One of the articles in my portfolio was an article about how protein works, which I’d written as a copywriter for a health and nutrition company. The hiring manager for the tech docs team had a PhD in biology, so she had some knowledge about protein. She was impressed by the writing sample and later told me it was this article that connected with her and got me the job. She felt I had clearly explained a complicated process.

What does a “typical” work day for you look like? Feel free to describe with as much detail as you’d like.

I try to plug into the agile flow of my project team as much as possible. If you’re new to agile, I definitely recommend reading Jeff Sutherland’s book Scrum. It will explain how to integrate with engineers on a software team, since nearly everyone today follows agile/scrum processes to some degree.

In following agile, I look at the items assigned to me for the current sprint (two-week cycle) I’m working on. I like to select three of the tasks and write them on sticky notes that I put at the bottom of my monitor. This helps me focus during the day.

Here are some typical tasks I might work on during a sprint:

• Draft project plan for new project
• Describe REST API endpoint in Swagger spec
• Meet with engineers for explanation of a component
• Update code samples in previous version of doc
• Create architectural diagrams that show a structure and workflow
• Create overview material for a new product
• Draft release notes for new features of a product
• Meet with engineers to review changes to API endpoints
• Create a video tutorial showing a complicated process
• Rewrite poorly written legacy content
• Review instructions an engineer wrote and include them in the documentation
• Troubleshoot errors in PDF outputs
• Create proof of concept for documenting long JSON objects in API requests

In agile, you have a backlog of items that represent the bulk of work in a project, but you don’t try to tackle them all at once, nor do you graph out a projected timeline representing a waterfall that breaks down the exact work you’ll cover for the next six months. Instead, you focus on items you think you can accomplish during a two-week period, and then when the sprint finishes, you demo the work you’ve completed.

At most software companies, hours are flexible, so I can somewhat come and go as I please, but I usually put in about an eight-hour day, arriving at about 8:30am and leaving at around 5:30pm. I take time for lunch, go on a walk, and sometimes read blog articles on breaks. If I’m absorbed in a project, sometimes I’ll work at home, especially if I’m trying to figure out some aspect of a tool or if I’m learning the technical nuts and bolts of a platform or programming language.

My tech writing colleagues are all virtual, with two colleagues in Arizona and one in the UK. We use instant messaging and meeting conferencing tools to interact. It’s okay that we’re not close to each other because it’s more important to be close to the engineering teams building the products we’re documenting. I sit in an open office environment right next to the project manager, quality assurance engineers, and other team members.

All of the doc team members contribute in a Mercurial repository using Jekyll, a static site generator. We’re all using the same project code, pushing and pulling updates, making commits, and interacting within the documentation repository.

What does technical writing look like in the next 5-10 years? How might a person just starting out prepare for such a future?

For the next 5-10 years, there will be a continued proliferation and diversification of tech comm tooling, because it’s getting easier to build and deploy tools. There are many code bases you can leverage to build your own tooling that exactly fits your company’s needs.

I think DITA will continue to grow, particularly lightweight DITA, because there are many component content management systems (CCMS) and other platforms built specifically to parse and process this content. In contrast, many of the more unstructured formats like Markdown don’t allow you to graduate to a larger CCMS to manage it all.

Nevertheless, static site generators and other Markdown-based tools, particularly browser-based tools, will also grow in popularity, though more so for smaller companies and for more technical projects.

API documentation will be the main staple of tech docs, because almost all companies will be producing APIs that allow different clients to integrate the company’s services in custom ways. Technical writers will write primarily for developers using these APIs and other associated tooling, such as SDKs, reference implementations, and other developer platforms.

There will be fewer tech writers focused on instructions for user interfaces (GUI documentation). The content these tech writers do produce will be tightly integrated into the interface itself.

For tech writers to thrive, they will need to know some programming and be in tune with how to write instructions for developers. They will focus on how to integrate code, whether that code involves calls to an API or some other technical implementation.

For API documentation, REST API specifications like Swagger (now OpenAPI) will be the norm and will integrate more fully with other documentation tooling, especially online tooling. These specifications will be parsed by platforms that host and manage documentation. The platforms will read the spec-based documentation and transform it into robust, interactive and sharp looking docs.

Nearly everything, including documentation, will be browser-based SaaS services, so the whole Mac versus PC compatibility issues will fade away.

If tech writers work locally with file-based content, they will publish that content dynamically by simply committing the update to a Github repository, which will trigger a continuous build process on the server where the content is hosted.

What do you like best about technical writing? What do you like least?

I like creating something from nothing. Initially there’s a blank page and a lot of confusion around a product, but then little by little you figure out how it works. You write documentation that gives clear instruction to perform a specific task with the product, and then you document another task, and another. After a while, you have a lot of instructive topics that explain how to use the product.

You start to add some visual polish, such as workflow diagrams, screenshots, and maybe a screencast. You add some step-by-step tutorials, maybe some some interactive features that let users try out endpoints. Before you know it, you’ve got a full-fledged help system that lets people learn and use the product.

This is what makes the career of technical writing so fulfilling – creating something that didn’t exist before, and which consists of highly valuable information (not fluffy marketing copy) that people find useful for learning. This learning empowers them to be better at their jobs and other ambitions.

What is the most difficult part of being a technical writer?

It’s difficult when you’re trapped by legacy tools and outdated processes and can’t change. When you have hundreds or thousands of pages of documentation in an old format, it can take months of tedious, monotonous work to convert it over to a new format.

Persuading your colleagues to use the new tools and format can be equally challenging. And when you have doc for different products that exists across various formats and platforms, with colleagues who aren’t as tech savvy or interested in exploring and experimenting with new systems, it can be tough to push forward.

But little by little, you can change things. It might take more than a year or two to actually implement a new process, but as long as you have good managers and leaders who understand the larger vision and scope of what you’re trying to do, you can be successful in changing these situations.

9. If a person seeking their first technical writing job wanted to get hired onto your team, what are the three most important things you’d tell them to do?

1. Create a portfolio of persuasive writing samples. Hiring managers want to see that you can write. It’s okay if you’re not writing in simplified technical English or following a particular technical style guide. Teams want to know that you can write clear, flowing sentences with correct grammar, well-organized ideas and other structure that make the content readable.

2. Show that you’re technical. Learn HTML, CSS, JavaScript, and maybe a main programming language like Java, Python, or C++. You won’t make it as a technical writer if you can’t learn on your own, so demonstrate some of your technical knowledge with your own projects and demo apps that you code yourself.

3. Develop some interpersonal skills. You’ll need to interact skillfully with engineers and other team members to get information. People want to work with people they like, so learn to listen, ask questions, share information honestly, be friendly, responsible, and so on. People skills can go a long way in selling yourself.

10. If you could give only one piece of advice to your younger self just starting out in technical writing, what would it be?

Don’t trust any instructions that you read. Test everything out yourself. This is particularly important in developer documentation environments where the steps to actually test out the code may be challenging and involve complicated setups.

Without the ability to test content on your own, you’ll rarely create help content that is easy to follow and error free. If you can, try to get in the user’s shoes as much as possible by using the products yourself.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.