Building a portfolio

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, no, your blog might not really contain the writing samples that a potential employer would like to look at.

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
• Content authoring tools: OpenOffice Writer, GoogleDocs
• Image manipulation tools: IrfanView, GIMP
• Publishing tools: Microsoft HTML Help Workshop, HelpMaker Help Authoring Tool
back

Pro bono projects
• http://sourceforge.net/
• http://contributing.openoffice.org/writing.html
• http://www.gnu.org/doc/potentialauthors.html
• 
  Why a video sample? Because a large proportion of the population are visual learners.
back

 

Play play

I made this crossword for the conference newsletter of STC India's annual conference that happened last week at Bangalore. Take a shot. I'll post the answers 3 days from today.

The crossword is not interactive, so you might want to take printouts... To see a bigger picture, click on the crossword.


To see a bigger picture, click on the clues.

Answers are here.

 

When the ToC spins out of control

---------------------------------------------------------------

This post has a post script written about 45 days after the original post. And a second postscript almost six months from the original post date.

---------------------------------------------------------------
Early this year, I wrote the install guide for an enterprise-level reporting application. The application itself is pretty easy to use - once it's installed properly - with intuitive UI elements etc. It's the installation that's a bit complicated. The product has three separate components which, while they can be installed on a single machine, will in a real scenario be installed on three (and possibly four) different machines. Let's say the components are A, B, and C. The installation order should be, in sequence,

1. Install and configure A
2. Install and configure B
3. Install and configure C

The steps differ for Windows and Unix. So, at first, my ToC looked like this:

and the expanded ToC looked like this:
Thereafter, things got murkier. A and B ride on top of pre-installed RDMSs, which effects the configuration steps. The installation itself has two threads - manual and automatic - which further complicates matters....

Version 1.0 of the product was releasing, like, day-before-yesterday, and without much time on hand, I ended up with a document that had the following ToC:
Every time I looked at it, I puked. But my dev team loved it - they found navigation a breeze and assured me that it'd be sysadmins who'll be reading such install guides and sysadmin minds work pretty much like theirs, and NO, it would not be a problem for the reader.

Two months into the release, the product is well-received, we're working on an upgrade and feedback starts trickling in...the install guide has all info but it's difficult to figure out what is located where...once I am at a page, it's difficult to figure out what's Next and Prev...there are too many "related links" on a page and I get confused (this last bit is not my doing - it's a DITA thing. All subtopics in a "family" or a "sequence" topic get automatically linked to each other).

In short, nope, sysadmin minds were not working the way the dev team said it does. I pretty much suspect a glazed look came over their eyes when sysadmins expanded the ToC and saw all those nested and more nested topics. I also suspect none of the sysadmins read the checklists and high-level steps I'd included in the "Planning the installation" topic.

In this post, I am thinking aloud about restructuring the ToC. Here's what's on my mind:


So, instead of readers navigating like this:

they can now navigate like this:
Am still thinking, though, if there's a better way to present the information...
---------------------------------------------------------------
Post script 1 dated November 6, 2009
I am leaving the ToC alone. What I'm doing is pulling out a buried topic and moving it right to the top, plus calling it prominently in the default home page of the online help. This topic has an installation matrix, and road maps for common deployment scenarios. People, when pointed to this hitherto-unseen topic, exclaimed, "Thanks! This is tremendous help."

Lesson learnt (from Post Script 1 response)
Findability is important. In-your-face findability is absolutely important.

[aside]"She dwelt among the untrodden ways...Half hidden from the eye! Fair as a star..." [/aside]

Post script 2 dated March 10, 2010
Because the road map was such a success, we're toying with the idea of automating it - answer some questions about your deployment setup and get an on-the-fly custom install guide.
---------------------------------------------------------------

 

Bad docs rarely mean bad sales

My father is more than 65 years old - which means he is officially a "senior citizen" entitled to tax breaks, travel concessions, blah blah. It does not, however, mean he is entitled to special consideration from his children (who continue to treat him like he's the dad that dropped them off to school but often mixed up the timings of the son's school with the daughter's).

So, when I got a blank SMS from my father (a few days ago, he'd been given a cell phone by my mother), I did not panic. I calmly rang him up (from 1500 kilimetres away) and asked, "Why on earth did you send me a blank SMS?"
"Did I? But I am still trying to write the message; how did it reach you already?"
"Oh? Did you ask Mom to show you how to write messages?"
"No, she's in the shower. I thought I'll look at this tiny booklet that came with the phone."
"And?"
"This is what it says under 'Message'."

"Hmm, did you press 'Send' after you wrote the message or before?"
"I could not figure out Step 2. It says 'write'. How do I write? I want to type H, then O..."

Problem 1: Step 2 does not say how to write a message, neither does it link you to another place in the doc that might have instructions on how to write the message.

"Then you must have pressed 'Send' before you typed anything. Now, look carefully in the manual and see if there's a topic called 'Writing a message' or similar."
After 2 minutes of silence,
"Yes, there is something called 'Write text'."

"Okay, so now you write the text and send it to me."
"No, wait, it says 'press the key repeatedly'. Which key?"

Problem 2: Which key does "the" refer to?

By this time, I had lost patience and mom had finished her shower, so, within 5 minutes I got an SMS from dad. It read "How were the mangoes we sent across last week?"

How was this episode relevant to me as a technical writer? Let me count the ways:

1. It reinforced two of my firmly held beliefs:
   
   1. Do not assume your reader to be as tech-savvy as you might be. Do an audience analysis and write for the lowest common denominator (remember Manmohan Desai and Prakash Mehra?)
   2. Do not make the reader go hunting for bits and pieces of info. Give complete instructions in one topic. It's okay to be verbose if that's what it takes to completely describe an action.
2. It added one more incident to my observation that badly produced "help" rarely effects buying decisions. Not at the retail level, anyway. I'll still go buy a handset from this equipment manufacturer because their handsets are good.
   
   Which might mean - technical writing is a cost activity, not a revenue or a profit activity.

 

Task flow - Analysed?

I took the following screenshot from the website of my credit card company. I was at the website trying to see if the payment I had made yesterday had been effected.

What is not quite right in the picture?

Would it not be better to tell me (the user) right away that if I use PayNet (which I always do), I cannot see my payment history through this interface? That, if I want to find out the status of my PayNet payment, I would probably need to call up customer service?
How about the following picture?

Is it not simpler, smaller, clearer? Does it not communicate upfront about what it can do and what it cannot?

Now, if only the designer who created the user interface had approached the interface as a user would have...

What is the point in telling me AFTER I have selected the dates , clicked Go, and waited for a few minutes, that I cannot view my payment history if I paid through PayNet?

Website users have a short attention span and do not read the entire page from top to bottom before they begin doing the task at hand. They quickly scan for the numbered steps, and start off following the instructions step-by-step. If the prerequisites (or, limitations) are not stated before the numbered list begins, the users can only get frustrated. Like I did.

User scenarios, anybody?

It was while leafing though the microwave guide, trying to find something, that I realised those good souls at the techpubs department of the microwave company had probably not done a user-needs analysis.

Before we go any further, let's first profile me. Female, Indian, grew up on mother's cooking, manages a home and a career, hates eating out, is always rushed for time. A microwave, they say, is handy for such people. It even (!) cooks Indian food without using as much oil (or time). So, fine, here I was trying to cook Indian food. I was making myself some aloo-dum and wanted the steps to:

1. Heat oil on high, throw in the seasoning, reduce heat.
2. Wait for a minute, increase the heat, throw in the aloo cubes, stir, cover.
3. Wait for two minutes or so, reduce the heat, let it cook.
4. Take out cooked aloo-dum and eat with puffed rotis cooked separately.

I was looking to combine steps 2 and 3 - I wanted to keep the stuff on increased heat for a few minutes and then get the microwave to reduce the heat automatically without manual intervention.

The microwave guide had no instructions for this scenario. Which means, I had to hover over the microwave for two or so minutes, manually reduce the heat, and ...
Two minutes is a long time for anyone rushed for time. Heck, even a Hindi film song gets over in two minutes. If I have to hover around the oven for two minutes, I might as well use the good old gas burner. So, I remembered the techwriter's Law No. 1: RTFM*

I did. And found nothing. It has a nice section on Indian recipes, with nice preset buttons that you can use to cook stuff. Nice. But it still did not tell me anything about setting the cooking cycle for multiple stages. The closest it got was this:

No, I wasn't cooking chicken tangdi kebab, thank you.

All Indian cooking, if my knoweldge serves me right, goes through a cycle of increase heat -> decrease heat -> increase heat -> decrease heat. This manual, meant to accompany a product that was being sold in India for Indians, didn't tell me how to.

---

* RTFM stands for Read The Fucking Manual. Back

---

Just in case you're wondering - the brother figured it out. He looked at the manual, tossed it aside, looked closely at the buttons, tried a few press this - press that combos with still-raw food (we ate it after those several experiments of his), and figured out the combo. I'm not sure if I'll ever look at that manual again.

 

The engaged reader

I was at my neighbour's. Their seven-year old boy came out of the room, put on his going-out chappals, and was turning the door-lock to open the door and go out when his mother said, "Why are you going out? Should you not be studying for your English test tomorrow?" The boy replied, "There is no more space in my brain."

We live in an era of information overload, the just-google overload. And, because everyone can write (!), we also live with community-contributed growliths such as Wikipedia. Here's a picture of a Wikipedia page that is trying to tell you what Twitter is about:


Noticed the excessive linking? There's a hyperlink in almost every sentence. Most of the time, the hyperlinked words have no relation whatsoever to the task at hand (which is, explaining what Twitter is about). Here are the superfluous links:

But just because the information is there - somewhere - on the Web, it HAS to be linked. ! @ # $ % And never mind the distraction - or the possibility of the reader clicking such a link and navigating away from the page and on to a (duh!) competitor's page (like, Facebook). The reader would be walking away from the page, declaring there's no more space in the brain. But hey, wait, was it not your goal to engage the reader?

Here is a screenshot of something that resisted the urge to overlink, and succeeded in keeping the reader focussed.
Noticed the immense possibilities of linking this paragraph provides? Almost every bullet point screams "Go, Go, Go". But because there's no clickable door to leave, the reader stays on the page. Engaged.

Style Quiz - The Economist

The Economist has a quiz up at its site. I took it and got 9 out of 12. What does that mean? Well, this:



If you too want to take the quiz, click here.

 

Writing for the vacuum

I write for people I never meet and most likely never will. Of course, we have stuff such as "audience analysis" that helps us frame a mental picture of the reader we are writing for but, in reality, I write for people I never meet.
Consequently, I never get feedback from my readers. Of course, we have review rounds, and we have tech-support reading our documents and troubleshooting, and all that stuff but, in reality, the user for whom I wrote the manual never gets back to me. Usually.

This is a pet gripe of the techwriters I've met. "We don't get feedback from the real reader", is what they say.

True. But hang on! How many of us techwriters have ever given such feedback ourselves? How many of us have even bothered to look at this and give feedback:



What happened to the Do Unto Others principle? Why carp when you're also the one who cannot cast the stone?

Word Mutants

The Washington Post's Mensa Invitational had asked its readers to take any word from the dictionary, alter it by adding, subtracting, or changing one letter, and supply a new definition. I thought that was fun, so here's my attempt:

With a letter added

• prayfer: a prayer for the appearance of a specific object in the Christmas stocking


• compunter: a computer that helps you place bets on software-offshoring companies in yet-to-be-developing nations


• sufferling: a child of insufferable parents


• abstinthe: to abstain from drinking absinthe while reading Wodehouse


• extravagrant: to stay out of suitcases in the presidential suites of grand hotels


• celeberate: when clueless celebrities gather in a TV studio to berate the policies of the government

With a letter deleted

• banstand: a covered outdoor platform, across the busiest crossing of a city, where crowds gather for lighting candles to fight terrorism


• univerity: a college that preaches universal truths


• faceboo: to join a Facebook group created for taking potshots at a person, an object, or an idea

With a letter changed

• inferface: a biometric interface that has sensors to figure out if your face has the characteristics of a jihadi killer


• singelton: a gay singer


• designame: to create self-explanatory designations from proper nouns. For example, Chief Satyam Officer


• conpetition: a pre-judged competition on a TV reality show


• euphomia: the feeling of intense happiness experienced by a megalomoaniac