Adobe FrameMaker

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

Stitcher radio

Adobe FrameMaker

Professional Technical Writing Careers -- Questions and Answers, by Steve Goldberg

Oct 7, 2012 • beginners

During the fall and winter semesters, tech comm professors often ask students to interview professional technical writers to get a better sense of the field. Having answered a few student inquiries already, I decided to invite other professionals to respond to student questions, and then to copy me so that I could post their responses as a guest Q&A post on my site. The following are responses to student questions from Steve Goldberg, a professional technical communicator who works for Venda in London. 

Hi Jake,

I'm happy to answer your questions. First a little about me to add some context. I work for Venda, a software company, in London which provides a SaaS eCommerce platform. We have three technical writers and my role focuses on producing overview documentation for our clients and staff, producing requirements gathering documents (usually in Excel), helping developers write technical documentation and copy editing it, and administering our documentation system, which uses Atlassian's Confluence.

I have been a technical writer now for nearly two years, and I had no significant work experience in the field before that. My background is technical in the sense that I have an interest in computers and HTML, but my educational background is in Philosophy -- I have a BA in Philosophy & Social Policy and an MA in Practical Ethics. Now, to your questions.

What preparation did you have for your current job?

I am located within the front-end team, which is the team that manages the HTML of a website, which is to do with look-and-feel and functionality that you see when you visit a website (rather than the back-end, which is more to do with how it functions 'behind the scenes'). I had always grown up loving computers and had built some simple websites myself, so understanding how their HTML works is essential -- though it should be pointed out that I really only needed a basic grasp.

My history in philosophy and ethics proved to them that I am capable of investigating how things work and clarifying the things that developers say. Someone once said to me that I am effectively a translator: I take what the developers are saying and convert tech speak to 'real world' speak as it were. My education taught me excellent use of the English language as well as how to structure documents and understand what my audience wants.

Since joining I have been on a technical writers course to train me for my job and have attended meet-ups and conferences, which lets me interact with out tech comm professionals and see how other people do their jobs.

What preparation do you wish you had?

Perhaps it would have been good to have completed a technical communications course before applying for a job as a technical writer. However, so far I don't think I've needed it because a lot of the skills required for the job I already have through my own education and experiences. Other than that, specific to my role at Venda it would have been good if I had more training in building websites, especially with technologies like JavaScript. A technical writer who knows a lot about a programming language is particularly valuable.

What skills do you consider essential?

  • Patience. Sometimes what developers have provided you is poorly written and disorganised. Like deciphering a dense philosopher or writer, you have to realise that the information is in there but you have to dig it out. This can take time.
  • Bravery. It seems strange, but telling someone who is busy and may not consider documentation important that they haven't given you everything you need to do your job requires strength. You have to believe that you're right and get them to make time for you. If they're unwilling, then you have to be ready to try different ways to get what you need, whether that is with some sort of gambit or by simply telling their boss.
  • Excellent grasp of language. You have to know English (if that's the language you're writing in) and know what words work and where they don't. The other technical writers and I have arguments over the stupidest use of words, but actually they're important. Should you repeat a word? Well, it adds consistency if it's a technical term but it can make the document seem a bit stale if it's overused. Knowing when to oversimplify and knowing when to put in extraneous details is important.
  • Attention to detail. All jobs say that you need this, but this is never more apparent than in technical communication. I read and re-read what I've written and um-and-ah about use of commas, sentence structure, whether the instructions are entirely accurate. Being precise cuts down on errors and support queries, which is an important metric.

What tools (including computer software) do you use most?

  • Microsoft Office for requirements gathering documents. Excel is actually really powerful if you know how to code conditional statements. When I joined and re-did one of our really out-of-date and neglected documents, I had project managers telling me that a four hour document now takes them two hours to complete. That's two hours of a PMs, clients, and the business's time that I have saved. Plus the whole experience was better. That's vital.
  • Atlassian Confluence for our documentation. Confluence is by far the best wiki / documentation software in existence. It is extremely powerful, easy to use and I regularly receive compliments on how well it is maintained and how easy it is to find what people are looking for. If/when I move on to another company, one of the first questions I will ask is "Do you use Confluence. If not, why?" It is expensive for large companies, but it saves time and money and is great for technical writers.

Do you use visuals in your work?

Because my work is largely regarding the front-end, I consider it important to show what I'm talking about at least once on a page. This is important with eCommerce sites as we have so many different pages and items of functionality. In the Functionality Guide, I normally start each page with a screenshot of what I'm talking about, whether it is the order receipt page or the Facebook Like button. Other than that, I think very carefully about whether to insert media. Too many screenshots ruin the flow of the page; not enough and you risk people having no idea what you're referring to.

If so, how are these visuals generated?

Typically screenshots of web sites are taken using the Awesome Screenshot extension for Chrome. These are then edited in GIMP, which is a free image editing tool. It's simple enough to use and also has enough tools that it does what I want it to do.

Things like flow charts are produced in Microsoft Powerpoint 2010. They've actually done a good job to make it functional and easy to make good looking flow charts. There are some plugins for Confluence, such as Balsamiq and Gliffy, which can also do things like that and embed them into pages. However, they cost money and getting money for this is very difficult. I have to be resourceful and use free tools wherever possible.

About what percentage of your time on the job is spent on writing (as opposed to researching, training, etc.)?

It's really hard to say. Unlike the other technical writers at Venda, I have to manage Confluence, so it's not uncommon for a lot of time to be eaten up by administrative duties. I tend to do them as soon as someone requests them (e.g., new user requests, creating new spaces, setting up permissions, etc.) as I don't want to be a bottleneck for other people. Writing can often be done in short bursts or longer sessions. Training forms a small part of my job, compared to investigation and research, though.

Approximately how much of your time is spent collaborating with others?

All projects require some sort of collaboration. It is rare that I collaborate with other technical writers, though, except to check each other's work. There are so few of us that having more than one of us on a project is very rare and can sometimes cause conflicts about how something should be done. With non-technical writers, I often work with others. Quite often we will have one or two meetings a week to discuss what's happening and what should be happening and the rest of it I am left to do what I need to do. I feel there is a healthy respect for what I do at Venda so people don't tend to butt-in. They certainly offer feedback -- and this is crucial -- but there is no micromanaging.

In what ways do you work with others (technicians, designers, developers, editors, users, technical illustrators, etc.)?

I'm not sure what you mean by that exactly. But the way I am perceived depends on the project. In my day-to-day duties in the front-end team, I am just one of the guys and I have a steady flow of work to do. For projects outside of my team, I am often seen as a 'resource'. It's a somewhat dehumanising term, I guess, but that is the way others in the company are perceived too. Therefore, I tell them how much time I am to spend on their project and the manager will then provide me with an estimate on when something should be done, but this is kept flexible because of all my other commitments.

When it comes to people like designers and developers, frequently it really depends on who needs what from whom. If I need them to produce documentation or imagery, I will give them a list of requirements and tell them when I want it by. Likewise, if they need me to check something or write something for them, they give me the requirements and when they need it by.

What else do you do all day?

Drink coffee... smoke cigarettes... go on the internet. Oh -- you mean work wise. Well, taking breaks is actually important. I actually socialise with a lot of my colleagues during the day. It's vital to build up good relationships with people because then they feel like they can ask you for your help and are more likely to be flexible when you tell them about all the work you have to do. Furthermore, if you need their help or input, you're more likely to get it.

I try to take an interest in what the developers are doing -- this is important as I will likely have to document it later. This allows me to understand why they are doing things a certain way and to point out things they will need to put in the technical documentation. Plus, they are often glad to get a non-technical perspective on things, especially if they have a problem.

As I mentioned, I also administrate Confluence. This could be a full time job in itself sometimes, so I have to find more efficient ways of doing things. Having some technical skills of my own, I am able to enhance Confluence by writing macros or new processes to do things automatically. This can really help all users to save time and get a better experience. I even gave a lightning talk at the Atlassian Summit (their big conference) about how to write macros to save everybody time.

I also spend time helping people to get their department documentation in order. We don't have a lot of technical writers so I have to help people in other departments. I help them produce templates and give them guidelines on how to do it themselves.

What was your biggest surprise/learning curve when you left college for the world of work?

I was amazed by how competent I actually was at doing the job despite not being technically trained for it specifically. I was pleased my philosophy degrees had value! Other than that, just starting off in the office environment can be a bit of a shock, but I am with good people and once you know the ropes, you start to learn the office politics pretty quickly. Having a good manager and people around you who can tell you how to do your job is a boon.

What are your major sources of complaint and satisfaction on the job?

Biggest gripes are not getting what I need from people. Sometimes, too, having too much on your plate and people expecting it to be done by a set time is a horrible feeling. Sometimes I have to do things akin to data entry, or other very repetitive tasks. The boring administrative parts of Confluence are a waste of my time and distracting, but someone has to do them and that someone is me.

The sources of satisfaction are when people tell you that you've done/doing an awesome job. I won the inaugural employee of the month for all my work and I was over the moon and humbled to be given the accolade. I have numerous people telling me that it was well-deserved, and being recognised by your peers for your contributions is the highest prize you can receive. It's also nice when a software release cycle comes to an end and work 'dries up' a little. This means I can relax as I have few deadlines and I can take some time off to just do nothing.

I hope I answered your questions.

-- Steve Goldberg

follow us in feedly

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include the following technical communication topics: Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, and certificate programs. I'm interested in information design, API documentation, visual communication, information architecture and findability, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.