Writing Technically: December 2009

This is the text version of my presentation at the STC India annual conference at Bangalore last week. It is a long post.

What is a portfolio? Let's see what the Compact Oxford English Dictionary has to say.

That's four meanings but for this blog post, we're interested in #2. Just like a set is a collection of well-defined objects, a portfolio is a collection of objects intended to show your ability in the field of technical communication. But why is a portfolio needed in the first place? Well, for one, because job ads ask for it.

A portfolio shows writing and editing capabilities, ability to create different document types, and experience with tools of the trade. A portfolio is your business card - it plays a large role in determining whether you get that interview call.

Now, the question is - why do you need to create one? Don't you already have a portfolio? Here are three questions that I've been asked often, and my response to those questions.

Can’t I use samples from my present workplace?
Nope. We work for hire and the employer owns every piece of work that we produce in the course of our employment. Let's look at it from another angle: Let's for a moment assume you work in a car factory. You are on the shopfloor, along with your colleagues, building a car. When the car's ready for delivery, can you drive it away and park it in your garage, claiming because you built it, you own it?
We cannot use any of the work that we do at our workplace anywhere outside your workplace unless our employer tells us to. Or, permits us to.
Now, let’s face it – how many of us want to walk up to our manager and say, "May I use this Demo, that I created, as an item in my portfolio?"
If I remove all proprietary information from the pieces, can I use them?
Nope. Think back to the car example. Assume that the car is factory-painted yellow and has a dancing fairy affixed on its bonnet. So, if you spray-paint the car green, and throw away the fairy, is the car yours? Not at all. Not only does it still belong to your employer, created at the employer's workplace using the employer's resources, it's now been tampered with without the employer's permission!
Can’t I send the URL of my blog as a sample of my writing?
Heck! Since when did a blog become a sample of technical writing? Anyone can write. Even poets can write. Let's assume John Keats has a blog. Instead of writing something like this (the "desired" format)
he would've written something like this:

When I have thoughts WordPerfect may cease to be I only have to press the CtrlF4 key And behold my docs high-piled in charactry Within Microsoft Word's own new domain Held like rich garners the full ripen'd grain That can be cut, copied, and pasted again Their shadows, with the magic hand of chance I only have at the Standard toolbar glance For selections to move on the page and dance Of the wide world I stand alone, and think All it takes is a DELETE key, and ding My words, all selected, to nothingness do sink

So, what do you do? This:

Arm yourselves with the required resources
Create a portfolio of writing samples that are relevant to the technical communication field
Showcase the portfolio to prospective employers

Let's look at these three points one by one.

Arm yourselves

Learn how to write technical documents. Unless you know how to write, you cannot write that which is to be written.
Learn how to write techdocs. About doing your research and gathering inputs. About what kind of information to include in your document and what information to leave out. Learn how to write in a structured manner. Learn about information chunking and how to categorise your material into conceptual, procedural, or reference documents and topics. Learn to visualise the kind of reader who would be reading your document and tailor your writing for that reader and that kind of audience. Become familiar with the basic documents that a technical writer is expected to work with, and learn about what goes into those documents – the purpose of those documents, the structure, the content. Before you actually begin to write, learn how to write.
Then, write. Review what you've written, correct your errors, write some more. And, get someone else to critique your writing. What should you be writing on? We'll come to that in a moment but in the meantime, use pen and paper and write (many companies administer their impromptu writing tests on pen and paper. Even today.)
Get ourselves a writer’s toolkit. See this list of free-to-download-and-free-to-use tools I've used myself. After you've made yourself a workbench with these – or similar – tools, familiarise yourself with them. You don't need to learn every feature and every little detail. It is sufficient if you know what all the tool can be used for, and if you know how to use it to do what you want to do.
After learning the tool, go back to your pen and paper writing samples, and redo them with these tools.
Work on some projects. See this list for suggestions on where to go looking for real-life projects outside your paid job. Why should you volunteer to be a technical writer for these projects? For one, it demonstrates your commitment to the profession, and your ability to work with teams that are geographically distributed. Also, it is a live, real-time, hands-on example of documenting a live, under-development project – and therefore, it demonstrates your ability to understand an application while it is still not complete, interact with coders and understand requirements and specifications, AND plan and deliver the kind of output that's best suited for the project.

Create a portfolio
Here are some suggestions of what can go into your portfolio.

A How-To procedure document
A specification, explaining how something should work
A quick-start guide
An installation guide
A reference book, like an API guide or a glossary

Reviewers like to see at least one example of an information type for a specific purpose and audience - for example, installation and administration guide, user guide, tutorials or learning material, multimedia. The tools you use for creating these samples is not important; what is important is how you analyze the needs of your audience and how you tailor your information to meet those needs.
If you are being interviewed for a junior level, do have a sample that has user instructions for a simple task.
If you are someone with a couple of years of experience, try to have a sample of an installation guide. In particular, a configuration guide.
If you’re someone who is more experienced, it might be a good idea to show that you can translate a use case document, SRS or FSD into user instructions. Your volunteer projects can contribute to all of the examples that I listed above. An appliance that you use at home lends itself very easily to a User manual. An activity that you taught someone in your family becomes material for a procedure topic or a tutorial. A roadblock when you were learning a tool can be turned into material for a troubleshooting guide or an FAQ. There are no limits, really. Just use your judgement and create the samples for your portfolio.

Showcase it
Now that you're ready with your portfolio, show it to the world.

Introduce each sample by giving some context. This is important because you would, in all probability, be showing an excerpt, not a complete piece. Mention the principles you used for creating the sample. This is important because they demonstrate your ability to figure out why you did what you did. Highlight some of the challenges you faced. State the constraints, and mention what could've been done to work around them or overcome them. Keep the introductions as short as possible.
Create a soft copy of your portfolio (burn it on a CD - not many employers are willing to risk using virus-philic pendrives) and carry it to your interview.
Constantly review, and add to your portfolio. Over time, weed out weaker samples. Samples should showcase the breadth of your experience and expertise. Like I mentioned earlier, for someone at a junior level, simple task topics are fine but as you gain experience, try tackling more complex topics and also other modes of delivering content. For a non-text example of Help, see this video.

You're now ready with your portfolio of samples.

List of tools