Author Archive akredshaw@gmail.com

Would I like technical writing?

Before you invest time, and possibly money, into getting into a technical writing career, you should first decide if it’s the kind of job you would like.

Keep in mind you probably won’t identify with everything in these lists, but if technical writing is a job you’d like, you may see some familiar patterns here.

Questions to answer – The big 3

There are lots of possible questions to answer to know if you would like technical writing, but I think these might be the big 3:

  1. Technical: Are you interested in technical subjects?
  2. Writer: Do you enjoy writing?
  3. Teacher: Do you find it worthwhile to explain things to people?

Technical

You are interested in all kinds of technical areas, maybe researching things that interest you, or reading books in technical areas.

You like to do some technical projects just for fun. Do you like configuring your computer OS? Ever tried writing your own program? Do you like setting up smart home devices? Have you taken things apart just to see how they work?

You are your own technical support. If you have a computer problem, you don’t call support, you figure it out yourself. If your wireless stops working, you fix it yourself. You fix all your smartphone issues, and maybe those if you’re friends or family’s as well.

You like news articles or TV broadcasts about new technology. You like to keep up on the state of autonomous vehicles. You think AI is cool. You like reading about new inventions. Cutting edge technology will always be fascinating to you.

You like researching all kinds of things. You don’t just read about new technology, but sometimes read more deeply about it because you want to know how it works – How are robots made? How does AI work? Could it ever be self-aware? What would it take to establish a colony on Mars? If someone asks you the time, you want to tell them how to build a clock.

You might be a fan of science fiction. I could be off on this one, but I’ve found that science fiction and cutting edge technology look a lot alike, which makes both exciting. Anything futuristic is fun. Therefore, you might like science fiction movies and books. You may sometimes hope you live long enough to see…the metaverse, house robots, flying cars, etc.

Writer

Writing has been an interest of yours for a while now. I had an 8th grade teacher who encouraged me to write, and that’s where my interest started. You might have similar stories.

You write a lot of lists. You may be the kind of person who has lots of lists for things. You like having your thoughts organized, as well as your schedule.

You write instructions for your future self. Once you figure out how to do something, especially something technical, you like to write down how you did it so you know what to do next time. You have lots of these sets of instructions written somewhere.

You like to read or write in your spare time. You may have an interest in writing a novel, or maybe you already have. You may read yourself to sleep at night. Even when you read a book, you might wonder exactly how it was written, and wonder if you could do the same thing yourself. You may write a blog, or lengthy social media posts.

You get satisfaction from a well written paragraph. I mean the kind of feeling you get after you have written, rewritten, revised, and edited your own work until it’s as good as you can get it. Reading something that you’ve written well just feels good. It feels like a worthy accomplishment.

Teacher

I didn’t just add this because I was a high school teacher for so long. I really believe a technical writer is inherently a teacher at heart. As such, you are good at explaining things to people, and you get some satisfaction from it. 

You want to pass it on. If you learn something new, you probably can’t wait to tell someone what you learned. My father used to joke about a kind of person that if you asked them what time it was, instead, they would tell you how to build a clock. That’s pretty extreme, but maybe you’re a bit like that.

You love teaching people things. My father used to joke about the kind of person that if you asked them what time it was, they would instead tell you how to build a clock. You might be a bit like that. You like explaining things to people. Maybe you were the one who helped one of your siblings with homework. Perhaps you want to be the one to teach your own child certain things. I taught both of our boys how to read.

You are good at explaining things to people. You may find in conversations, when someone doesn’t understand what one of your friends is saying, you know how to say it so it makes sense to everyone. Maybe you did this in school, interpreting what the teacher said to your friends.

The day-to-day job

Another way to know if you would like this job is to get an idea of what it looks like on a daily basis, and decide if that sounds good to you.

Every company is different, but here are my observations:

  • Meetings
  • Planning
  • Research
  • Writing
  • Iterating
  • Revising/editing/proofreading
  • Training/learning 

Meetings are important as a technical writer, because you’ll have to talk to people to get the specific needs they have, any due dates or launch dates, pain points customers are experiencing, short term and long term goals they have, and more. You may also need to meet in order to have them review what you’ve written if they don’t seem to want to do it otherwise. You’ll probably also have regular meetings with your manager, as well as product managers, or other stakeholders just to see what’s coming soon or how you help them with known pain points.

You’ll find yourself doing more researching and planning than writing. You may need to research technologies that are new to you, terms you’ve never seen before, or more depth on the product you are writing about. If the project is very large, you may write up a formal documentation plan, or proposal, that you later share to get agreement from all stakeholders before moving forward to the work. For that you’ll need to plan a timeline, who signs off as an engineer, product manager, technical program manager, solutions architect, legal, etc. How will you do the navigation? Will it be on page or several? How will the information be organized? Will other pages need to be updated as a result?

Write your first draft, knowing it won’t be pretty, and probably will have plenty of mistakes. That’s what first drafts are for.

After your first draft, you probably want to have an engineer or other technical person look it over to see if it’s accurate. It may be that when you revised something, you interpreted it incorrectly, and now it’s inaccurate. Perhaps there have been changes to the product and the document is no longer correct. I have had instances where the person who gave me the original docs to work from had errors in what they gave me as well. You at least want to make sure that everything is technically accurate.

This may take several iterations. They add some notes and you try to make the changes. You ask again if that was what they wanted. Sometimes you may go back and forth several times before everything is correct and is easy to read. Iteration and revisions are often done at the same time. You will revise your work again and again. I read through each page a number of times, looking for things to change, ask questions about, or remove altogether. You will check your work with a style guide to make sure it lines up. If you have an editor on staff, they may read it as well.

If you can, and your company is supportive, you should also spend regular time learning. You may take online courses, go to conferences, or just read up on new technology or trends related to technical writing. This is a job where to keep competitive, you should keep learning.

The good and the bad

Every job has positives and negatives. Here are some for the technical writing job. So what do you want first, the good news or the bad news?

Positive

  • The pay can be quite good. In fact, if you have an English, Literature, or Journalism degree, it’s one of the highest paying jobs you’re likely to find.
  • Tech companies sometimes have a higher caliber of benefits compared to other companies.
  • The job is often much less stressful than other jobs, especially compared to programmers or engineers.
  • You usually have a good work life balance as a technical writer.
  • You get to learn about new technologies before the rest of the public, which can be very cool at times.
  • It’s remote work friendly, and lots of remote jobs are available if you want them.
  • You can choose your hours at many companies, which is nice if you don’t like to wake up early, or like me, you do.

Negative

  • It can be very difficult to get your first job, which is why I write this blog.
  • Often people won’t understand what you do. That includes those you work with.
  • Often documentation will be an afterthought at your job. That means sometimes documentation may be requested just days before the product launches. At times they may even forget documentation altogether.
  • Some subject matter experts may be slow to respond to your questions, or may not respond at all. Chasing them down can get frustrating.
  • Some engineers might wonder why they even hired you, since everyone can write, right?

One neutral item I’ll add is that you will probably be multitasking in your job. I’m sure it’s not universally true, but I think it’s common to work on more than one project at a time. I tend to work on 3-5 at a time, with each in various stages of the process. It might add to some stress, but it also keeps things from getting boring.

You can always do more research into whether you might like technical writing or not. YouTube is a good resource. Reading job descriptions can also give you an idea of what’s involved in the job. Reading comments from reddit in r/technicalwriting might help as well.

What should I study first?

August 13, 2022 Comments Off on What should I study first? By akredshaw@gmail.com

If you want to get a job as a technical writer, you will have to get technical. Since I’m often asked what to study first, I’ve put together some guiding principles so you can figure out where to spend your time learning the technical subjects. 

I won’t tell you what to study first, but I’ll give you what you need to make that decision. As usual, I’m assuming you want to document software using a docs-as-code approach, which is where my experience lies. 

For minimum requirements to get a job as a technical writer, see the first section of Getting experience – Part 1

If you have a technical background

If you have a degree in computer science, or you have been a software developer in the past, you don’t need as much practice with the technology as you do writing and thinking like a technical writer. What would probably help you the most is a technical writing certification. It may be from a college or other institution. A certification will demonstrate to employers that you not only know something about writing, but that you have the skill to write technical documentation. It also proves you are interested in technical writing as a career. I mention this because some employers will assume that since programming pays more, you will end up doing that instead of technical writing. Completing such a certification shows you are serious about this profession. 

If there are some items you don’t know on the list below, go ahead and learn them as well.

If you don’t have a technical background

This is for all of you with a BA in English, Art, Social Science, etc. You will have to put a heavy emphasis on learning the technology to get into technical writing. Here’s what you need to learn.

List of technology to learn to be a technical writer

  • A programming language – just the basics
  • Git
  • Command line
  • HTML
  • Markdown
  • Web API documentation
    • OpenAPI specs
TechnologyDifficultyEstimated time to learnNotes & resources
Programming languageHard2-4 monthsOnly at a basic level. Here is some guidance on learning a programming language.
GitMedium1 monthLearn this through githowto.com. Out of the 51 lessons, the first 28 will be the most useful.
Command lineMedium2-4 weeksDepending on your OS, go to YouTube and type of the the following:learn command line for Windowslearn command line for Mac OSlearn command line for LinuxThere are a lot of good videos out there.
HTMLMedium3 weeksThere are probably a million HTML tutorials online. Learn the basics, plus how to create tables.
MarkdownEasy2 hrsThis is really easy. Learn it with Markdown Live Preview.
Web API documentationHard3 monthsSee Documenting APIs from Tom Johnson. There are several Udemy courses on this topic you can buy as well.
OpenAPI specs
(Part of web API documentation)
Hard1 monthOnly 1 month if you already know web API documentation basics. See Step-by-step OpenAPI code tutorial.

In order of importance (just the numbers)

If you use my spreadsheet for job results in my area, you’ll see a number of jobs results for each skill.

  1. API = 26
  2. HTML = 23
  3. Markdown = 22
  4. Python = 20
  5. Git = 15
  6. OpenAPI = 2

Notice that rather than include “programming languages” in the list, I listed “Python” instead. The reason is because if I wrote “programming languages,” phrases like “know a language such as Python” would be excluded. If I did not put it in quotes, it would look for the words programming and language, but not necessarily together. Anyway, Python comes up the most often in the list when they ask for experience with a programming language.

In order of importance (my view)

Here’s my view of what is most important to study. You’ll notice some differences. This is a bit subjective, but I do have reasons. The reason I did not put APIs at the top is because although API documentation is listed fairly often, it is less common for it to show up in actual interview tests. In all the companies I’ve interviews with, I think they tested me on APIs twice. None of those were FAANG (Facebook, Apple, Amazon, Netflix, Google) companies, by the way. Whereas, all the FAANG companies, and several others I’ve interviewed with, had me read code in a programming language and tell them what it does.

What do employers tend to focus on the most in interviews? What’s highest on their list? Here is an estimate from my experience in the San Francisco Bay Area, interviewing at many of the top companies, including most of the FAANG companies. 

  1. Programming language
  2. Web API documentation
  3. Git
  4. Command line
  5. Markdown
  6. HTML
  7. OpenAPI specs

Some things to keep in mind

You may imagine that you want to spend all your time at the top of the list and work your way down, but remember, Markdown only takes a couple of hours to learn. In that case, even though it appears much further down, you probably want to get it done early in order to add it to your resume soon. 

Something else to consider is that learning some of these subjects can get tiring after an hour or so. You need breaks so your mind can remain fresh and you don’t get burned out. That’s why you probably want to be working on 2-3 of these items at a time. When you get tired of learning programming, you can play with Git for a while. And then maybe HTML. This way you learn more in less time, and don’t get burned out on any one subject.

You should also know that if you start learning API documentation in any depth, you will learn the command line and possibly Git along the way, since these tools come up frequently when working with REST APIs. 

If you want to read more about what you can expect in a technical interview, read The technical writing interview – Part 2.

Happy learning!

What are APIs anyway?

July 30, 2022 Comments Off on What are APIs anyway? By akredshaw@gmail.com

Introduction to APIs

When people use the term APIs, they are not all talking about the same thing. This used to confuse me early on, so I’m going to give you a very quick tour of APIs. If you want more in-depth knowledge, there is a ton of information online.

To start, API stands for Application Programming Interface. It’s a way that software can exchange information with other software. Since knowing how to document APIs is in very high demand for software technical writers, I’m going to also provide resources for learning more about each type. 

There are two main categories of APIs. Library APIs and web APIs.

Library APIs

Library APIs are software components. You don’t want to have every possible software library already included in your program or else it will take up a lot of space and it could really slow down your program. Instead, you include the software components you want when you need them in your program. For instance, if you’re not including images in your program, you don’t need to import an image API. How do you learn about these APIs? When learning a programming language, you usually learn about some of the common library APIs for that language. If you were learning to program for Windows, you might start learning about the available Windows APIs. 

Examples of library APIs

Web APIs

Web APIs are also software components that can communicate with existing software, but these can be accessed through the web. Web APIs have been increasingly popular in the last few years, because anyone with an internet connection can access them, often for a fee. Web APIs come in several different types. Here are the most popular ones.

REST APIs

Representational State Transfer. This is an architecture for the web. You can request, add, update, or delete resources. It is also the most common type of web APIs available, and one that shows up in a lot of technical writer job descriptions. If you want an excellent free course to learn how to document REST APIs, go through Tom Johnson’s API documentation course

Advantages

It uses HTTP, which the internet is built on. It also utilizes the newest innovations of the internet, such as HTTP2. There are a lot of free tools for use with REST, and much of what is out there is open source, so companies can take the source code, modify it, and make it their own. When OpenAPI specs are used, these APIs can be easily navigated for the average user. 

Examples of REST APIs

gRPC APIs

Google Remote Procedure Call. This is Google’s version of RPC, and it calls methods (a programming term for actions) on the other machine directly. You can call methods across the internet as if they were already on your machine. While there are fewer gRPC APIs in use, the number of transactions worldwide are the highest. For instance, YouTube uses gRPC. Imagine how many transactions per second happen on YouTube! These APIs are much more often closed to the outside, so others cannot use them. You can learn much more about gRPC here.

Advantages

It’s fast. Really fast. In general, it’s about 7 times faster than REST APIs. It’s also great for programmers, because they can use a programming language they already know, and it’s like calling a method on another computer as if it was the same computer. 

Examples of gRPC APIs

GraphQL

Data query and manipulation language, which includes the runtime to make these queries. Whereas REST was an architecture, and gRPC was a way to call methods, GraphQL is a query language. With it, you can request data, add to the data, change the data, or delete it. It was created by Facebook to solve some of the problems with REST APIs, such as overfetching or underfetching, or having easy ways to deal with different versions of the API. I won’t explain all of that here, but you can learn a lot more about it on the GraphQL Foundation page. That site also has a good tutorial for all the basics.

Advantages

GraphQL solves several issues that come up often with REST APIs. With REST, you request resources, and often several things are given in one request. For example, if you request book information, you may get the title, author, ISBN, and date of publication. But what if you only want the title. Then you are overfetching. You don’t need all the other information given. Let’s say you are doing this thousands of times for different books. It might be costly and take up most of your internet bandwidth, because you are getting a lot more information than you need. But GraphQL only gives you exactly what you ask for. Therefore, it is much more efficient. There are other advantages too. See the GraphQL Foundation page for more.

Examples of GraphQL APIs

Final thoughts

I learned recently that some companies are now using gRPC or GraphQL for the underlying API, but then use REST as the customer facing API. Evidently this offers some advantages, and is becoming more common now.

There are other kinds of APIs out there too, but these are the most common currently in circulation. I know I didn’t go into much detail here, but it’s a start, and you can use the resources I’ve provided to learn more.

Getting experience – Part 3

Get experience with an open source project

GitHub | Linux | GNU | Sourceforge

Common advice

The idea that you can get a job in technical writing by volunteering to write documentation for an open source project has been around awhile. This advice often appears in blog posts, tech writing forums, and advice columns. The prevailing logic is that you can add to your portfolio by writing documentation for some of the many open source software projects available. This shows off your tech skills as well as your writing ability, and is a kind of real-world experience. It sounds good on paper, but has some real problems. Let’s begin with a story.

Story 1

There once was a woman who dove into an open source project, writing some of their technical documentation, which eventually led to her getting a job at Facebook. True story. It really happened. You can read more about it, or even watch the video here: From Open Source Volunteer to Full-Time Tech Writer.

This is a really inspiring story, but before you start looking for an open source project to contribute to, consider the following:

  • She had been an aerospace engineer for 15 years.
  • She said nothing made sense (in the open source project) for quite a while.
  • She first got noticed through her own blog, rather than anything she published on the open source site itself.
  • She was trusted with maintenance of the main website for the project after a while, so they gave her an unusual amount of access.
  • The open source project she worked on had an astronomy module, and her undergraduate degree was in astronomy.
  • She mentored students for the Google Summer of Code because of her degree and background. Her mentoring also helped her make the connections she needed to get the job at Facebook.

Now let me tell you another story. 

Story 2

Once upon a time I started learning API documentation, thanks to Tom Johnson’s excellent course. I finished his course, and tried to contribute to an open source project, as he recommended. I couldn’t do it. I figured I just didn’t know the material well enough, so I went through Tom’s whole course again. Again I tried to find an open source project to contribute to, but again ran into a brick wall. Knowing I was still no expert in API documentation, I went through the whole course a third time. It always takes me three times to learn something well anyway. After the third time, I felt like I really knew this stuff. I jumped on GitHub and tried to find somewhere I could contribute to API documentation. I went through hundreds of projects, but couldn’t find anything I could contribute to meaningfully. 

Granted, I’m no expert, and maybe if I had spent months really digging into things, I could have made some progress. With enough time, most things are possible. Still, here are some of the issues I ran into:

  • I didn’t initially realize the differences between library APIs and REST APIs. I should have figured this out, since Tom does mention both in his course.
  • Many of the projects just weren’t active anymore.
  • Developers did not have time for me. Remember, most of them do this in their spare time, after their day job.
  • Related to the point above, often their requirements for a technical writer is that they should read the code and figure out what’s going on with little to no help. Then they should contribute. Later, I learned that even seasoned developers usually take 3-6 months before they can understand a complex code base well enough to contribute. This means, it would likely take me around 6 months, even if I was a seasoned engineer.
  • Many projects were so complex, I could not even figure out what they did, let alone actually contribute to any API docs for it. 
  • I also couldn’t figure out how to install the software, or all the dependencies I needed to get started.
  • Project contributors often assumed I understood a lot of inside knowledge of their technology or related technologies, such as dependencies.

Keep in mind, a developer would need to give you certain things before you could even get started.

The minimum you need to document an API

  • The API base path.
  • Endpoints.
  • All possible methods and parameters, with descriptions.
  • An API Key (If required), or how a user can get an API key.
  • Status and error codes with what they mean.
  • Open lines of communication with a developer who can quickly answer any questions about the project.

How about if you decide you want to document code samples rather than APIs. Documenting code is a big part of being a technical writer as well. In that case, here’s what you would need from the open source contributors. 

The minimum you need to document code

  • Code samples.
  • Detailed notes or a description of what each sample does and how to use it.
  • Direction on what parts of the code can be altered to fit the developer’s needs.
  • Open lines of communication with a developer who can quickly answer any questions about the project.

However, most engineers expect you to read the code and find these things out yourself.

Even if you are documenting code samples, and not APIs, the developer will need to give you a lot for you to get started. Because the truth is that most technical writers do not create their own code samples. They are given the samples by software engineers, along with some sort of explanation. Yes, tech writers ask more questions to fill in the missing pieces. They add the parts developers might assume others know, just because they know the code so intimately. Technical writers also improve the instructions, grammar, organization, and navigation. Sometimes they even find mistakes in the code. But most don’t pull the code out of their own heads, nor do they intuitively know what the code does or how it’s used.

Often, the most difficult thing to get is the last item in each of the two lists above. In fact, it is nearly impossible, for all practical purposes. 

What to look for in an open source project

  • The project interests you. You might spend a lot of time here.
  • You can figure out what the software or API does.
  • The project is active, with an active community.
  • They clearly have a need. They either say so in their contributions page, or there is a ticket that says so, or you see a need and offer to work on docs and they say that would be great.
  • One of the contributors is willing to walk you through the code, or API, telling you what each piece does. This may be a huge barrier. They may think that if they were to spend that much time helping you, they might as well just write the documentation themselves.
  • They already have good comments in the code that you think you can use to get started.
  • Someone who is part of the project is very responsive and patient to answer your questions quickly.
  • You believe you can write documentation from scratch for the project, not just touch up existing pages.
  • You can actually get the software installed (if it requires installation) and get it working in order to try things out and document the software. This may require the installation of certain compilers or interpreters for programming languages, frameworks, other open source projects, and more.

If you already have experience with a technology, or a programming language, you can start there. For instance, if you’ve been learning about Blockchain lately, you may want to look up Blockchain projects. Or if you have learned some Java, you can look up Java software. There are many great guides for how to contribute to GitHub. But first let’s decide if you should even start down this road.

If those you reach out to say they expect you to read the code and figure it out, move on. Unless you can really do that. If you can, ignore my bleak advice. Maybe you can really do this.

To make headway in an open source project, it may take months to even start to get your bearings on a project. And then more time to contribute. Even such writing samples, an interviewer may still ask, “So, how many years of full-time technical writing experience do you have?” I have had that question asked of me more than once in a job interview. No writing samples can get over that obstacle. 

What employers actually want to see in sample work

1. Step by step, numbered instructions that include:

2a. Code samples in some of the steps, clearly explained.

or

2b. API docs, with endpoints, parameters, etc. with steps for how to use the API.

3. It’s all your work.

You must include 1, 2a or 2b, and 3 in order to be taken seriously by an employer. 

One issue with contributing to an open source project is an employer doesn’t know how much of it you did. Ideally, you want to create whole docs yourself. Adding a paragraph to a page will not get you a job. Fixing a readme page will not get you a job. See #3 above.

Will working on open source get you a job? Two more perspectives

I recently encountered this Reddit post:

Does volunteering like this actually lead to a job? Can anyone confirm they got a job by starting here?

After a number of people failed to answer the question, one person replied with,

The silence is pretty deafening.

That’s about what I expected.

I think this is one of the most often quoted pieces of advice out there that seems to have very little data to back it up. I have only heard of one person getting a technical writing job through contributing to open source. Therefore, this should probably be considered a fringe case rather than a normal pathway.

I prefer actual data, rather than”broscience” when giving out advice.

Another blogger says about this method:

I reiterate, this method (contributing to open source) is not advised for those seeking entry into technical writing or relatively fresh in the field. I say this because there’s usually very little hand-holding and you are expected to hit the ground running.

My conclusion

I am not going to say it is impossible to get a job by contributing to open source. I can only say that it seems hard. Really hard. I might also add it seems unlikely. However, if you are an ex-developer, or have specialized knowledge, maybe you can ignore this post and make it work. And if you have months or years to burn, you could probably find a way eventually.

For others trying to make the transition into technical writing, I would recommend that you go back and see my first two blogs for ways to get experience that might lead to a job.

If you know other people who have contributed docs to open source projects, which led to them getting a job in technical writing, I’d love to hear about it in the comments.

Getting experience – Part 2

April 16, 2022 Comments Off on Getting experience – Part 2 By akredshaw@gmail.com

Get any job in an IT industry, and try to work your way into a tech writing position

If you’ve been applying for technical writing jobs, you may have discovered that no one will hire you without experience. In that case, you may try getting a job in a technical company, and see if you can work your way into technical writing. If you are currently employed, you may do this in your current company.

I was talking with my colleague at work yesterday, and she said this was how she became a technical writer. She was originally a bookkeeper, but then approached her boss about doing some technical writing projects to help out the company. A few projects became more, until they changed her position so that she was a full-time technical writer.

Many jobs can work themselves into either a technical writing role, or allow you to gain experience so you can apply for such a job. But not all. For instance, if you mow lawns and you want to get into medical technical writing, you probably can’t get that specific experience in your current job. In that case, you may want to check out the volunteer section after this, or consider getting a different job.

Many companies can be a launching point into some form of technical writing. There is a very wide range of technical writing possible, so many organizations could benefit from some kind of technical writing. If you have a specific technical writing focus you are interested in, like tech writing for software engineers, then you may need to learn some things.

In order to succeed in technical writing, you must have both of the following:

  1. Subject matter experience and/or knowledge. Example: Knowing a programming language, common medical terminology and how hospitals work, military experience, nuclear reactor service repair experience (that one’s pretty specific). It all depends on what field you want to write in.
  2. The ability to write well and concisely. You’re able to write well, with a vocabulary appropriate to the subject, without wasting words.

You may already have one of the above. The truth is that for most people, both can be learned. However, you have to decide if you have the time or desire to learn them. 

If you know nothing about aerospace engineering, but you want to become a tech writer for that field, it may take months or longer to learn enough. But if you were in the military, where you worked on airplanes, you may want to see what technical writing might be available in that industry. Or if your father is a doctor, and you grew up working in his private practice, medical technical writing might be the thing for you. However, if you don’t already have any specialized knowledge, which was my case, you can still learn what you need to get into the field. I have other blogs on learning the skills needed for technical writing in the software industry, since that’s what I do.

On the other hand, if your writing is poor, or you are fairly new to English because your primary language is Hanti, then that is where you will want to focus your time. There are classes you can take, workbooks you can go through, or online training. Ideally, you want to practice writing and have a good writer who can critique your work and give useful feedback to help you improve. Getting a technical writing degree or certificate will also give you more writing practice in the kind of writing you will need to do as a technical writer. In my last blog, I discussed College programs that help you get into technical writing.

If you write well, and you already have some specialized knowledge that may be useful for a tech writing job, your journey may have less to do with learning, and more to do with convincing an employee to give you a chance. Gaining some kind of experience, along with shareable writing samples, can make all the difference.

The job you have now, or end up getting, may not be that important. Are there any technical parts of the company? Does anyone fix their computers? Is there anything technical going on here? Then get to know those people and offer to write how-to guides to make their load lighter. You can write a step-by-step one pager on how to fix the copier when it gets a paper jam. About how to backup the computer systems at night. How to run a complex report. Database SQL commands used often, with examples of output. Onboarding material for new engineers, or a new office manager, or a janitor. Any writing samples are better than none, but ideally, you want all your writing to meet these two criteria:

  1. It’s something similar to what you would create in your field of interest.
    1. Example: Writing how new engineers set up their computer environment will be more useful than how to make coffee in the breakroom if you want a tech writing job for software engineers.
  2. It’s something you can share. It could be publicly accessible online, or they will let you share a copy of it with employers or on your portfolio website. Make sure you ask for permission beforehand. There should be no company secrets or personal information in your work. Or you redact anything they don’t want you to share. 
    1. Example: There is a password in your onboarding instructions, so you replace it with “*******” or you change someone’s name to “Mickey Mouse.”

Here are some tech writing ideas:

  • Instructions for setting up the company VPN
  • A manual for new employees on their first day. What to do first, who to contact when they need help, job titles for those around them and how they interact with each other, a floor map, where to find supplies, etc.
  • The procedure for requesting new software.
  • How to set up Slack, and what Channels to subscribe to.
  • How to control the building heating and cooling system.
  • The Git workflow used by your engineers, so they can share it with new software developers.
  • A list of FAQs (Frequently Asked Questions) to be used by customer support representatives.
  • The correct process for requesting time off at your company. Include how to add an “out of office” auto response in their email software, and how to set their Slack status to “vacationing” for that day.
  • The procedure for reserving a conference room.
  • How to set up a meeting. Include how to check the other employee’s calendars in order to avoid meeting conflicts.

If your company has an IT department, ask them if you can write any needed reference material for them. You may do this when you have extra time. See if they have something within your capability that you can create. How-to’s, glossary, diagrams, guides, a knowledge database, or anything else. Ideally you would gather information from someone in that department. They can give you notes, or even walk you through what they want documented. If it’s complicated, record it on your phone so you can make sure to get it right when you write it out later.

If your company is smaller, and you have one poor, tired tech employee who fixes all the computers and keeps things running, help them out. Tell them you will write procedures to share with everyone for how to fix many of the most common issues that come up. For instance, how to look up runaway processes and kill them when a user’s computer starts responding slowly. Maybe write a guide for how to prevent getting so much spam, or how to recognize email phishing. Perhaps make a simple guide for how employees can tell if they have a virus. These could be compiled in a small manila folder and distributed to everyone, or put on an internal website for reference. By offering to help in this way, your computer technician may start leaning on you for more and more. Make sure you can share most of these externally, and keep adding them to your portfolio. 

Let’s say your company is so small you don’t have anyone who does these things. Your business contracts with a tech business that performs computer upgrades and repairs, and clears computers of viruses. Tell your boss, or whoever is in charge, that you can write some easy to follow instructions so that employees can solve the most common issues on their own. You can save the company money by having to call the technician less often. Who would turn that down? If your manager says the work you do is more important, offer to do it after work or on weekends. Pace yourself. You don’t want to burn out. With permission, keep a copy of each project you finish.

Consider writing a proposal for upgrading to a new software package, or just a new version. Do the research on both versions. Get geeky, but make it understandable. Show all the benefits and example cases. Present this to your manager or whoever is in charge of IT.

Some jobs might lend themselves more to getting technical writing experience than others. If you’re in technical support, you can write down everything you learn and put it in an easy to read format. Quality assurance jobs might need documentation for common procedures or SQL queries used most often. At almost any technical job, you could write down what you learn and procedures you use. Make the instructions easy enough for others to follow. See if you can distribute it throughout your company, or just your department.

You can document things for internal teams, or customers of your products as well. I have read a number of stories where someone started helping out their company in these areas and then later their job title changed to “technical writer” because their manager realized they were saving the company money. They basically created a job for themselves from inside the company.

Keep in mind, this may not always happen. You are trying to get experience that would be similar to the kind of technical writing you want to do in the long term, and get writing samples that you can share. And of course, with all this practice, your writing will improve, and so will your technical knowledge.

Volunteer

If you cannot find valuable experience through your current job, or you are still between jobs, you can gain experience through volunteering. If you already have a relationship with a nonprofit organization, that might be the best place to start. For instance, if you attend a church, mosque, temple, or other religious gathering already, see if they have any office needs for a procedural manual. If they need a new computer set up, you could do the work if you know how, and at the same time, write step-by-step instructions for the next time someone has to do this. If they need to consider buying new software, you could volunteer to do the research and then create a professional paper with the following sections:

  • The problem / or background. This means, why do they need new software? What’s their reasoning? Or why do you propose they need new software, if the idea came from you.
  • Possible solutions. What software titles did you research? Give a short description of each.
  • My advice. Add a well reasoned argument for one particular solution.
  • Appendix. Include all competing software products you considered, with extensive pros and cons listed for each. Also include professional reviews summarized for each product
    • Pros and cons may include the price, features, release date, compatibility, company support, etc.

Here is a PowerPoint proposal I made for a company as a part of the interview process (you might notice some mistakes I made). I mostly don’t recommend you do free work for someone, unless purposely volunteering, but at least I did get the proposal as a sample of my work. Keep in mind, there was nothing proprietary in the proposal, so I’m not giving out company secrets here.

If you have a child that goes to school, you may be able to volunteer there. The school library might be a good place for this. Librarians are often understaffed. Ask if there are any procedural manuals you can create. Since all modern libraries have computers accessible to look up books, databases, and more, see if they might need an easy to follow set of instructions for any of these. You may create a single page, with icons, and a list of menu commands, with how to get started. Or, for more in depth writing, see if they need a tutorial for new employees or volunteers for how to register with all the accounts, databases, websites, and other online resources they will use regularly.

If you are not already involved in some way with a nonprofit, you can do a search online for “volunteering in my area,” and you will likely be presented with a lot of options. Some places to volunteer might be:

  • Animal shelters
  • Schools (especially if your kids go there)
  • Aquariums
  • State park systems
  • Hospitals
  • Museums
  • Churches, Mosques, Temples, and other places of worship
  • Other religious organizations
  • Senior living facilities – Teach a class on how to use a computer, cell phone, etc. Write a clear and concise manual for it

Besides some of my previous examples, here are some things you can do:

  • Create instructions for daily work
  • Create educational / training material
  • Create a computer manual for daily tasks – If you want to get into computer tech writing

When you pick a place you want to volunteer, remember to approach them with humility. They may turn you down. You should be honest with them.  Tell them you would like more work related experience in technical writing. Then ask about certain pain points they might have. If they are understaffed, they may not have time to write onboarding materials for new employees. Procedural manuals are often an afterthought because employees are too busy putting out fires to write proper instructions for others. They may be using old software, but no one has time to research what’s new to create a proposal. Let them know you just want to help. Some might feel nervous because you are a stranger. Approach them in the middle of the day when everyone is around. If they turn you down anyway, or say they don’t really have anything for you, that’s fine. There are a lot of other nonprofits that would love to have free help. Again, if you already have a relationship with one of these organizations, or know someone who does, that will be the easiest way to get in.

Work for a startup

My first real experience writing technical documentation for a company was with a startup. A friend of mine from my church had been helping to start a tech company that wanted to create a social media platform based on blockchain. He knew I was looking for work and asked if I wanted to volunteer to get experience. They needed someone to write a white paper for them. Since it was my first time writing a white paper, I bought two books for my Kindle on how to write a white paper, scoured the internet for advice on it, and checked out some books from the library. It was great experience. I learned a lot as I did research on blockchain, current social media platforms, and how the technology would work. I interviewed a subject matter expert, an engineer in Singapore, who worked for the startup. We sent messages back and forth for a couple of months as I iterated on the paper. I also included charts, graphs, and screenshots. At the start, I asked them if I could include the paper on my portfolio website, and they agreed. 

Startups, especially really early on, sometimes can pay very little, if at all. But they have lots to do. AngelList is a website where you can find startups that might consider hiring you short term or just for one particular assignment. Once you register, you can search their job listings to see if anything might work for you. 

In my next blog I will write about how to get experience by contributing to an open source project.

Getting experience – Part 1

March 3, 2022 Comments Off on Getting experience – Part 1 By akredshaw@gmail.com

The problem

“How can I get experience in technical writing when all the entry-level jobs require experience?” I’ve heard this a lot. It’s perhaps the most difficult issue to overcome when trying to get into technical writing. Just today I looked up entry level positions for technical writing on Indeed. I saw only one in my area, and here’s what it said:

3-6 years? I have seen many other entry level positions like this, usually requiring 1-3 years of experience. How is that entry level? Of course, you can always apply anyway, but even in interviews I have found getting around a lack of experience extremely difficult.

Here are the minimum requirements to get a technical writing job:

  • A college degree. Usually in a technical subject or English, Communications, or Journalism. If you already have experience, they will often accept a degree in any subject. Yes, a degree is pretty much always a requirement. There are exceptions, but they are rare.
  • Writing samples to share, proving you can write technical documentation well.
  • Experience
  • Experience
  • Experience
  • Knowledge of a programming language. Usually Java, Python, JavaScript are mentioned. Sometimes they also mention C++ or C#.
  • Knowledge of the tools. Markdown, git, command line. If going the DITA route, knowledge of FrameMaker is common.

In this post, I will talk about those middle three. You could probably already tell I was setting you up.

This is one of the most problematic issues for aspiring technical writers, because how do you get experience when even entry-level jobs require experience. Here are some suggestions.

  1. Get an internship
    • You have to be in college to get into an internship.
  1. Get into a college program in technical writing that has ties to the industry and promises to place you when you graduate
    • These are seldom the higher paying, software development jobs, but any experience gets your foot in the door.
  1. Get any job in an IT industry, and try to work your way into a tech writing position
    • You still have to get in. Not so hard if you have a degree in IT. Harder if it’s in English or Journalism.
    • Work in a place that doesn’t do software, but you can offer to help write some procedure manuals or something to get started.
  1. Volunteer
    • Write manuals for someone. Find a church or other nonprofit that could use some technical writing, such as a procedure manual.
    • These also tend not to be software docs, so you would still have to work into software documentation after getting your next job, if you can.
  1. Work for a startup
    • Again, this may be more of a volunteer job, or with very limited hours. I did two projects for a startup after a friend from church mentioned they had a need. 
    • Even after that, companies often ask, “How many years of full-time experience do you have as a technical writer?” Notice how that’s worded?
    • You can really beef up your portfolio this way.
  1. Get experience with an open source project
    • This is problematic, but sometimes possible.
    • Create your own open source project and document that.
      • You have to have at least some technical knowledge. 
      • If you want to get a head start, check out this Reddit post

Some of this is research heavy, so I’m going to get into each of these in more detail in upcoming posts. This will give you an idea of where I am headed. Let’s start with the first two.

Technical writing internships

Technical writing internships can help you get your foot in the door in getting experience with technical writing. Any experience is helpful, and even if the internship is not for developer documentation, you can still add it on your resume under “Experience,” which can make all the difference. Keep in mind that many of these internships will pay you as well, so an internship is not necessarily a vow of poverty.

The minimal requirement to get into a technical writing internship is usually that you are currently enrolled in college. However, not many require that your major is technical writing. Common requirements are majors in communications, journalism, English, software engineering, or another IT major. One post I found on Indeed said that business majors were welcome. For some internships, I found that any major was acceptable.

I also noticed that some require you to have been in college for two years already, or be a year away from getting your bachelors degree.

A lot of large tech companies offer internships, such as Google, Facebook, and Amazon. Sometimes there is a lot of competition for internships, while at other times, or depending on the company, you may be able to land an internship without too much trouble.

Handshake recommends starting a search for an internship up to a year ahead of time. For more on college programs that offer inroads into the technical writing profession, read the next section.

College programs that help you get into technical writing

I asked around about what technical writing college degrees or certification programs offered either an internship, or job placement upon completion. Having discussed this question with someone in leadership at STC (Society for Technical Communication), I was told that most universities and certification programs now require an internship as a part of their course of study.

San Jose State University, for their technical writing program, says on their website, “We have a strong job-placement record and help coordinate paid internships with local employers during the summer and the school year.​” This is in Silicon Valley, near where I live.

Not far from there, I heard that Berkeley has a technical writing program that offers internships and may have connections to the industry as well.

Further from me, in India, Metapercept Technology Services offers a Buddy-up with a technical writer program. It is a training-to-internship-to-hiring program. Internship and hiring are based on the participants performance during the training and internship.

For programs that don’t directly connect you to an internship or job, most help you create a portfolio, which is a step in the right direction. 

If you are considering either a certification program or college degree in technical writing, I would make sure they offer a way into the industry directly. At a minimum they should offer an internship, or even better, connections to the industry with a high rate of students being placed at companies. Since it is so difficult to get started without actual experience, I would recommend rejecting any program that only helps you build your portfolio. Remember, experience is king. If they can get you experience, that’s what counts. The best experience would be for the kind of technical writing you want to get into, such as writing documentation for software developers. 

I will continue going through this list in my next post. In the meantime, feel free to leave a comment below. I especially welcome comments about programs or schools that offer not only training, but experience in the field that might lead to a job.

The importance of humility

When trying to get a job in technical writing, or even once you have one, humility can serve you well. Sometimes humility is learned the hard way, by running into a wall, or being turned down a few dozen times. Fortunately, we don’t have to wait for that to happen to learn humility. Here are some thoughts I have about its importance in your job search.

I don’t know what I don’t know

Here’s the thing. I think I’m pretty smart. I’ve learned some things trying to get into technical writing, and on the job. Sometimes I think I’ve arrived. But that’s not true at all. I know what I know. But I also don’t know what I don’t know. You can take a look at the comment at the end of my blog on What kind of technical writing job should I get into? and see that some of my assumptions were incorrect, at least for other locations. While it may be hard to hear that, it helps me to grow. The truth is my knowledge was incomplete. Someone else knew something I didn’t know.

It’s good to keep that in mind when trying to get into technical writing. It’s always hard to get rejections from companies. However, if they send something besides a form letter, it may really help to hear what they thought you needed to learn. Other than more experience, add any skills they mention to your list. Then learn those next.

There are people around me that know more than I do

I worked with a lot of people in other jobs before I got to technical writing. I remember when I was a high school English teacher. One teenage girl in my class was the most talented writer I had ever seen. In fact I had to admit to myself that she was a much better writer than I was. She had command of the English language to such an extent that I finally told her she could probably make it professionally if she wanted to pursue writing as a career. She had other plans though.

This carried into when I got into technical writing. When I was a temp at Google, I learned that one of their values was that their employees should be humble. I appreciated this, because it would be easy to have a big head from working at one of the top tech companies in the world. 

If you are trying to get into technical writing, be a sponge. Surround yourself with technical writers, or experts on the subjects you’re studying. I joined the Society for Technical Communication (STC) to learn from other technical writers, as well as to hear about any open positions they knew about. Each meeting I attended, I came back having learned aspects of the job I hadn’t known about previously. I also heard about good and bad companies, and what I should even look for when checking out a company. Surrounding myself with people who knew what I didn’t know made a huge difference.

At the same time, I read a great deal from Tom Johnson’s blog, got lots of tips from Andrew Davis and Paul Gustafson (recruiters from two different companies), read lots of reddit posts, and listened to Write the Docs podcasts. 

There’s so much I don’t know yet

The list of what I don’t know stretches far beyond the list of what I do know. This will always be true. I can always learn more. Even from the complete newbie. I have had new hires where I work come up with ideas that I’d never thought of. If I would have stopped listening because they were new to the industry, I would have really missed out on learning something new.

The moment I think I have nothing new to learn, I begin to shrivel up in my career. This is especially true in a job such as technical writing. 

An interesting thing about some kinds of sharks is that they get water into their gills to breathe by swimming. They don’t even sleep, because if they did, they would suffocate. This is like a technical writer, or to be more broad, a human being. We begin to die the moment we stop learning, and all learning requires a degree of humility.

The same holds when trying to get a first job in technical writing. When I was training myself to become a technical writer I would learn one skill, demonstrate what I learned by writing a portfolio item using that skill, and add it to my skills on LinkedIn and my resume. Then I’d go to the next skill. Rinse and repeat, ad infinitum. Or as Dory would say, “Just keep swimming, just keep swimming.”

It’s not all about me

When I was trying to find a technical writing job, it seemed like my world got pretty small. I was consumed with my struggle to get a job. It wasn’t a bad thing for me to be focused, since I was the main breadwinner in our family. But at times I had to pull back enough to consider that I had a family, and I had friends. They had struggles, emotions, and whole other lives outside of my small world. Spending time with my wife, doing something fun with my kids, going to an STC meeting, or church event, were all important parts of my life. It was an act of humility to consider others when I was so focused on my own goals, but it gave me a better perspective on life, and made me feel better in the process. Because, in the end, when I got the job, I didn’t want to be alone. I wanted to share my joy with the others around me. In order to do that, I needed to invite them in throughout the whole journey.

I worked hard, I prayed hard

Not everyone is religious, but I am. I worked really hard when I was trying to get into technical writing. You can read about how I went about it on other posts in my blog. Besides working hard, I also prayed hard. My Christian faith is central to my life, so I prayed, as well as had a lot of others praying for me. It was a daily thing.

Humility, for me, was to realize that, while I could work really hard at this, only God could make it happen. And he did. That’s my testimony. Just like I couldn’t save myself, Jesus did that, I couldn’t make an employer want to hire me. I certainly wasn’t lazy, but the God I prayed to made a way for me, and I thank him for it.

The technical writing interview – Part 2

January 27, 2022 Comments Off on The technical writing interview – Part 2 By akredshaw@gmail.com

In this second post on the technical writing interview, I’ll focus on the technical section of the interview itself. For behavioral interview advice, as well as how to prepare for other general interview questions, see The technical writing interview – Part 1.

This post will be based on the kind of technical writing I do. It’s what I’ve heard some refer to as technical technical writing. Specifically, it uses the docs as code approach to technical writing. 

Most interviews I went through had five different sections, an hour each, with a different person doing each section. Yes, that’s five hours of interviews. One person was dedicated to the technical portion. For Amazon, I did this twice, going through the whole process for two separate teams. In these interviews, sometimes it was a software engineer who gave the technical portion, and sometimes it was a technical writer with a coding background.

What technical subjects to know for the interview

Reading code

First and foremost, they require you to be able to read and understand code at a basic level. This is true for virtually all jobs using a docs as code approach, or anything related to APIs or developer documentation. For that reason, knowing some basic programming is the number one skill to develop if you do not already have a programming background. 

During an interview, often someone would show me a simple program in my preferred programming language, usually letting me pick from Java, Python, or JavaScript. After I viewed the short program, they would ask questions such as (examples for Java):

  • Tell me about the parts of this program. What is this?
    • Example answer: a class. And here’s a method.
  • What is wrong with this program?
    • Example answer: It’s missing a semicolon at the end of the statement.
  • What does this program do?
    • Example answer: It stores a list of animals in an array and then prints out the third item.

The most in-demand programming language

When reading job postings for a technical writer, Java, Python, and JavaScrip probably come up the most.

  • Java – An object oriented language that can be a bit difficult to learn, although much easier than C or C++. It has also been around a long time, and is slowly fading in popularity due to Kotlin, a language created to replace Java. It still has quite a following as a powerful, multipurpose language. A lot of financial institutions still use Java.
  • Python – An easy to learn language. With Python, you can program in a functional or object oriented paradigm. It is among the most popular languages, and is used especially for data science, AI, and machine learning.
  • JavaScript – Developed for the web, it has grown to include desktop applications as well. JavaScript can be very complex and has many frameworks, modules, and other parts to learn to be well versed in its use. Above all, it is still used for web applications.

If you are just now deciding to learn a language, I would recommend Python. It is very popular and comes up all the time in job descriptions. It is also the easiest to learn at a basic level for an interview.

Just so you see some code here. I have below the same simple program written in Java, Python, and JavaScript.

Java

public class Program {
   public static void main(String[] args) {
       int a = 2+2;
       System.out.println(a);
   }
}

Python

a = 2+2
print(a)

JavaScript

var a = 2 + 2;
alert(a);

Output for all three programs:

4

What do you mean to learn these at a basic level?

If you use Sololearn, which I will recommend in a moment, you should make sure you are especially comfortable with the the material in most sections in the course. The sections I would especially encourage you to learn include:

Java

  • Basic Concepts
  • Conditionals and Loops
  • Arrays
  • Classes and Objects
  • More on Classes
  • Exceptions, Lists, Threads & Files

Python

  • Basic Concepts
  • Strings & Variables
  • Control Structures
  • Functions & Modules
  • Exceptions & Files
  • More Types
  • Functional Programming

JavaScript

  • Overview
  • Basic Concepts
  • Conditionals and Loops
  • Functions
  • Objects
  • Core Objects

While I consider these sections to be the most important for an interview, from my limited experience, you may want to finish the whole course just in case. Also, my experience is that to feel comfortable with a programming language, I have to go through the entire course three times. Here’s how it usually goes for me:

1st time throughI get the main concepts and try out the provided code.
2nd time throughI play with the code more, making changes to see what happens.
3rd time throughI am starting to create some small programs now from scratch, looking up things when I get stuck or can’t remember exactly how to type something. At this point I feel like I have a good handle on these lessons, and a good foundation for the programming language.

As I mentioned before, my favorite resource for learning a programming language is Sololearn. You can use the website, or my preference is to use the phone app. There is a free version, or you can upgrade to the premium version, which I recommend if you can. Either way, it’s a great place to learn a programming language. The cool thing about it is that as you learn, you can play with live code and even create your own programs from scratch and save them. Sololearn offers courses for all three of these languages, as well as several others.

Other technical subjects to know

Each of these only came up in one interview, but I’m sure if I had more, they might have come up more often.

Git

I was asked about certain Git commands. For example:

  • What command do you use to see the state of your work when using Git. Answer: git status.
  • What does git branch -a do? Answer: It gives you a list of branches in your repo.

Here is a great place to learn Git. If you get about halfway through this, you should know enough, not only for an interview, but for most jobs.

Command line

At one job interview I was asked about certain command line tools. For instance:

  • How do you list something at the command line? Answer: ls
  • How do you forcefully remove a directory along with all the files in that directory from the command line? Answer: rm -rf 

The easiest way to learn the command line is to look for a good cheat sheet and then try it on your computer. Keep in mind, Windows has different kinds of command line tools, and some of the commands are different on some. For Windows, PowerShell is probably the best, since it is the closest to what you would also use on a Mac or Linux. The commands are mostly the same, and it’s already built into Windows.

HTML

A basic knowledge of HTML is needed for technical writing, so at one interview I was asked about HTML. For this, I was given some text with notes such as:

  • Make this line a large header
  • Here is a paragraph
  • Add a line space here
  • Make this into a table. Tables are the most used HTML for technical writers

Then I had to write out the HTML for doing this. 

Sololearn has a course for HTML, but there are thousands of good HTML tutorials online to learn this. Just do a search for “HTML tutorial” and go for it.

Know the lingo

I have one other piece of advice, and it’s not quite as technical as the rest of this post. Learn technical writing lingo. You should know what an SME (Subject Matter Expert) is. Also, know that your Stakeholders are those who would benefit from the work you do. This is usually a manager or department that requested the work, or it may be your customers. 

Read a few articles online to familiarize yourself with the lingo. A good book that helped me with some of this, even though it wasn’t specifically for a docs as code approach was Technical Writing Process, by Kieran Morgan. The book was also helpful for learning to think more like a technical writer, especially in how to organize information, and how to create a procedure for the work itself.

Spend time writing out your answers to Part 1 of this series, and prepare for the technical knowledge section, and you may just get the job you’re interviewing for. Good luck!

The technical writing interview – Part 1

January 16, 2022 Comments Off on The technical writing interview – Part 1 By akredshaw@gmail.com

Congratulations, you got the interview! So, how do you prepare for it? You are going to prepare for it, right?

Preparation matters

One of two fates will befall you if you don’t prepare for your interview. When a question is asked, especially something open ended…

  • You have nothing to say and meander around searching for the right words to use, or the right story to tell. There are awkward silences throughout the interview. You lose confidence, and your interviewers have the feeling you lack communication skills in general. You also come off as someone who really doesn’t know their subject well.
  • You won’t stop talking, but get off topic easily, sometimes even forgetting the question. You waste everyone’s time, and by the end, some of the most important questions were skipped due to lack of time. You might come off as flighty, and unfocused. You also come off as someone who really doesn’t know their subject well.

On the other hand, if you prepare, your answers will be concise and accurate. You will have evidence for every claim you make, and will come off as someone who has deep insight into your line of work, the company, and this position. You also sound confident when you speak. 

So, how should you prepare for the interview? 

Write it out

It is imperative that you write this out. I use Google Docs, but use anything you like. My notes in preparation for my last interview, from which I got my job offer with Amazon, was 23 pages long.

Write out answers to the following questions, abundant notes, and more. Then go over them again and again, rewriting sections, and adding to your document. As the interview approaches, read it from beginning to end every day for at least 3-5 days, so answers come to mind easily in an interview.

Questions you must be prepared for

These questions come up all the time in interviews, and there is no excuse for not being prepared for them.

Tell us about yourself

Another way to ask this is, “Why don’t you introduce yourself.”

For this question, write out a short, one paragraph summary of you. You might include:

  • Married? Kids? No need for names.
  • Where you grew up, lived, went to college.
  • A few hobbies.

Do not start telling stories here. They didn’t really come to hear personal stories of your life, and time is precious. Just give them enough so they know you are human and have interests.

What are your strengths? 

Start with a list and then narrow it down. If you can’t think of anything, ask a friend or previous coworker. Once you have a list, narrow it down to your strongest traits, as well as those you know would be the most highly sought after for the job. For example: You have a couple of strong traits. You are very personable, able to start conversations easily. But you are also an excellent writer, with a degree in English and have done a lot of editing for publications. In this case, I would stress your writing rather than how personable you are, since it fits the main job qualifications better.

Write a list of strengths, but have a good top three ready for the interview.

What is one weakness you have?

This is always tricky. You want something that is true, but you don’t want to sound like a bad fit for the job. You also don’t want to sound like you don’t take the question seriously. “Sometimes I get sidetracked by learning the tech side of the job, and I have to focus again to get the writing done.” On the other hand, maybe yours would be, “I like my writing to be perfect, so sometimes I probably spend too much time getting every sentence just right.” Perhaps these aren’t too bad, especially the first one. There are lots of great articles online about how to come up with good weaknesses in interviews. I won’t belabor it here.

Why do you want to work at this company?

You’ll need to know what this company does and what makes them unique. I’ll talk more about background research later. Just make sure you know why you would want to work here compared to all the other companies out there. Make sure your answer makes them also feel good about what they do. “Because you are the largest manufacturer of silicon wafers in the country, and the industry has always interested me.” Another answer might be, “I love your motto that you want to be ‘the world’s most customer-centric company.’ ”

Why do you want this particular job?

Know why you like this line of work. Since we’re talking about technical writing, usually something about how much you enjoy technology, and also love to write would be appropriate. Also, how you love to learn new things, or be on the cutting edge of technological breakthroughs. You may mention your dual loves of coding and writing, if you know how to do both. These are just suggestions, but good ones you can use.

What is one of your greatest accomplishments?

This might also be worded, “What are you most proud of?” While you could talk about raising your two children, it might benefit you more if you can relate it to the job more. You could say, “I created an app in C++ that has been forked on GitHub over 200 times.” Or, “I helped write and publish a book on distributed computing last year.” Those are big ones, but it could be something like, “I wrote a tutorial for how to make a simple game in JavaScript.”

If you have had even part-time or volunteer work as a technical writer in the past, you can mention a project you worked on. Maybe you wrote a white paper, or created a website.

Do you have any questions for us?

This is almost universal, and you should be ready with a reply. It’s often the last part of the interview. Don’t ask about pay. It’s not time yet. Also, don’t tell them how much you’ve made in the past, or how much you expect in this job. 

If nothing comes to mind, what I use most is, “When will I hear from you about the results?” Then I slyly add, “I’ll be doing other interviews as well, so I want to know when I’ll hear from you.” It’s even better if you have an interview coming up and can say that you have an interview on Tuesday and want to know when they’ll give you their decision. 

One, this might speed up the process, because maybe if they don’t hurry, you’ll be gone with the first offer. Two, because it gives the feeling you are in demand, and they’d better move on this because other companies are starting to realize your value already.

Keep in mind that you don’t want to ask questions that you probably could have just looked up, like how many people are in the company, where you’d be working, what their top product is, etc. 

Background research

You should be good at this, since a lot of technical writing involves research. First research the company. Find their website and peruse it thoroughly.

  • What do they do or make? 
  • How did they start? 
  • Who started the company? 
  • Who is the CEO now? 
  • Have they been in the news lately? Why?
  • What are they focused on right now as a company?
  • What are some of their most popular products?

Write out all these things and more. Then memorize it.

Behavioral interview questions

Behavioral interview questions are very common in technical writing interviews. They have to do with what you have done when you were in a certain situation, or what you would do in that situation. Questions are usually in the form of “What did you do when…? or “What would you do if…?” Work through these kind of scenarios ahead of time and write down your answers so you are ready. You can find lists of common behavioral questions online.

Common questions might include:

  • What would you do if you had two managers who are giving you conflicting directives?
  • What if you asked an SME (subject matter expert) a question in email, but they wouldn’t respond?
  • What do you do if you have too many projects that are all due at the same time?

How do they hire?

Some companies have very specific kinds of people they are looking for. For instance, I recently read a post by someone who had worked at both Google and Amazon. They stated that both companies do their hiring with different overarching questions. Google asked, “How smart are you?” Whereas Amazon asked, “What have you done?” These are very different takes on what they are looking for.

Many of these companies have philosophies of hiring as well, or ways they go about it. Amazon uses the STAR format (Situation, Task, Action, Result). Google has certain Googleyness questions (thrives on ambiguity, values feedback, effectively challenges status quo, puts the user first, does the right thing, cares about the team), so you should prepare with those in mind. 

Write out all your experiences, skills, and accomplishments, and put them in these categories. Use the company’s framework to put your expertise into perspective. Spend a lot of time here, because these are the criteria the company uses when hiring. If you have limited, or no experience, insert your skills instead, or projects you created for your portfolio. Show that you meet every area of their requirements.

What’s their culture like (tenets, values, etc.)?

What philosophy guides their decisions? What’s their vision? What are their core values? What do they say about their culture? Copy these from their website and write out how all of your experiences fit in this list. Write down stories, maybe even from other unrelated industries, in the right section of the list. Write what values you like the most and why?

Amazon uses these leadership principles. Google says, “Our mission is to organize the world’s information and make it universally accessible and useful.” They also have the value of Googleyness, which I mentioned before.  

Meta (formerly Facebook), says for their culture: Move Fast. Be Bold. Be Yourself. If you want to know all of what they mean by that, I’m sure there’s a lot on their website about it.

Who are your interviewers?

If you are told ahead of time who will be interviewing you, see if you can find out a little about them online. I don’t mean to cyberstalk them. Don’t be creepy. Go ahead and find someone on LinkedIn, but don’t try to connect with them before the interview. Just see what is important to them. What’s their job title? Where are they an expert? Maybe get an idea of their personality. 

Mine the job description

To prepare, copy and paste the job description into your document. Read it carefully for everything they’re searching for in a candidate. For each item they want, write your skills and experience that relate to that next to the item. Then go to the next one on the list. You know this is what they’re looking for, so make it clear that you fit all, or most, of the things on the list.

That’s it for Part 1. A lot of qualified people don’t get the job because they have neglected to do their homework. Once everything is written out, revise it over and over, and also read what you have written at least once a day for several days leading up to the interview. Then relax and do your best. You’ve got this!

What kind of technical writing job should I get into?

If you’re looking for a technical writing job, it’s easy to get overwhelmed with all the possible job requirements. The truth is there are many types of technical writing jobs, and each has its own requirements. For that reason, there is no need to study all the requirements for every category of technical writing job. Picking a target type and working towards that kind of job can save you from being quite so overwhelmed and may get you a job faster.

While I’m not an expert in most of these, I can give you my take on what kinds are out there.

Keep in mind, I’m not going into subject areas much here. There are specialties in semiconductors, robotics, medical, networking, and more where I have no experience.

Basic technical writing

I call this basic, because it is not as technical as the next category. You won’t need to know any programming or have API experience or other really technical experience to do this type of writing. On the other hand, it’s not content writing either. Content writing is more like creative writing, mostly requiring writing skill and some interest in the topic. Basic technical writing requires some knowledge of, or interest in learning about, a technical subject, whether computer parts or bicycles, medical tools or washing machines.

It also requires some familiarity with certain tools. The most common writing tool used here is Microsoft Word, but might also include Photoshop, InDesign, Illustrator, and more. It would be good to know Google Docs as well, as it is used increasingly instead of Microsoft Word.

To prepare for these jobs, have a good writing portfolio using the tools listed above, as well as anything else you often see in job descriptions. Again, if the job description mentions reading code, DITA, or APIs, you are looking at a technical technical writing position, not a basic technical writing position. You can often get trial versions of most of these kinds of software, so pick one at a time (such as InDesign), and take a few weeks to learn it. YouTube videos and online tutorials may help, as well as anything already installed with the program itself. Then make a portfolio item using that tool and add it to your LinkedIn profile and your list of Technical Skills on your resume.

From what I can tell, basic technical writing pays about half of what a technical technical writer can make. For many, however, this is still plenty.

Technical Technical Writing

At my company, this is called Technical Writer Technical. These require more expertise in a technical subject, as well as a number of technical tools. For software companies, they usually want applicants to have programming experience or the ability to read code, or API and SDK experience. They also ask for specialized tools for the writing itself. There are different approaches to the writing workflow, and this determines which direction you might want your studying to go.

Since I mostly know the software industry, I cannot speak much about requirements for hardware technical writing.

DITA / single source / topic based

DITA stands for Darwin Information Typing Architecture. All sections of documentation are broken into these topics:

  • Concept
  • Task
  • Reference
  • Glossary

For this reason, another name for this is topic based technical writing.

One of the main tenets of DITA is that every topic should be reusable. In this way, everything written should be able to be used as needed in different articles. That’s why another name for DITA is single source. You write a piece of information once, say a concept. Then everywhere you need to introduce this concept, you can use the same concept topic you wrote earlier.

DITA is written in XML. The best free resource I have found for learning DITA is the free course at https://learningdita.com/. If I remember right, it took me 2-3 weeks to get through the course.

XML may be a bit cumbersome, but most people use software that writes the XML for them. FrameMaker is very popular, as is Oxygen XML, XMetaL, Easy DITA and a lot of others. To learn one of these, I first recommend you go through the above DITA course, and then see if there is a free trial version of FrameMaker. The last I checked, FrameMaker was the most popular on job descriptions, so I’d start there. Then try to write a tutorial using the software. Make sure you put that tutorial (in several formats) on your portfolio website. There are lots of YouTube videos and other resources online to get you started. There may be built-in resources to help you learn it as well.

After FrameMaker, maybe try some other kinds of software, so you can put that you have experience with it on your resume and LinkedIn too.

A note about Madcap Flare

MadCap Flare is an impressive software program that uses XML and is topic based. It has a lot of the important concepts of DITA, but is technically not DITA. My experience with it is that it is easier to use than FrameMaker, and can import DITA files. Here’s an article if you want to know the differences: What is DITA and How Does it Differ From MadCap Flare?

I recommend you get a trial version of Madcap Flare and write something for your portfolio website. Then add this experience to your resume and LinkedIn account.

As long as the subjects are technical enough, DITA and Madcap Flare technical writing can pay very well. It usually depends what you’re writing about. Both of these can be used for many subjects, both very technical and less technical. Of course the technical, such as software documentation, tends to pay more. If you are documenting software, make sure you learn a programming language. I have more about that in the next section.

Docs as code

The idea behind docs as code is that technical writers should use the same workflow and tools that software developers use. It is especially important that technical writers can at least read and understand a programming language at a basic level.

Other common tools to learn for docs as code are git, Markdown, HTML, basic command line navigation, Visual Studio Code or Atom, static site generators such as Jekyll or Hugo, and maybe GitHub.

If you don’t already know a programming language, you can learn one online or with a phone app. I recommend Sololearn (sololearn.com). For a beginner, Python is probably the easiest to learn and is in very high demand. You will notice it listed in job descriptions for technical writers often along with Java, C++, or JavaScript. But Python is the quickest to understand, and for most, I would recommend you start there.

You can learn Markdown in an afternoon. Learn it and put it on your resume, LinkedIn, and demonstrate something with it on your portfolio.

HTML is a little harder, but you can learn it in two or three weeks. Sololearn is a good place to learn it, but there are thousands of excellent HTML tutorials online for free. You will especially need to learn how to write tables for technical writing, since Markdown is really lacking in this area.

Learning git is required for docs as code work, and here is a very thorough and well written tutorial for git. You will not have to learn all of this to be very successful with git. If you get through the section on Merging (about half way through), you will do fine. Often for difficult git questions, people search the internet anyway.

To learn to use GitHub, you’ll need to create a GitHub account. To learn it, you can see many tutorials online as well as YouTube videos. It’s not hard to get started if you already have some git knowledge.

One benefit of learning git is you will already have begun to learn command line, since command line is a big part of git usage. In fact, navigating git and the directory structure for the files, is probably the main skills you will need for the command line.

The websites for Visual Studio Code and Atom have great tutorials already, and both programs are free. Use those tutorials and learn one of those programs, at least at the basic level. Learn how to write Markdown in one of them and see the output formatted correctly.

Static site generators all have websites with tutorials as well. As I said, Jekyll and Hugo are common, but there are others as well. Try installing one, and getting it to work. Create a page with Markdown and get it to publish. That’s a good start.

Docs as code tends to pay very high, since special knowledge of software development is required.
Docs as code is what I use for work, so you could say I am biased in this direction. Since it is not so strict with its format, like DITA is, I feel I can be more creative in the whole process. I’m sure DITA lovers, however, feel it has many advantages as well.