Saturday, October 11, 2008

Matters of Ownership (ethics)

I've seen job ads where the recruiting companies want to look at samples of an applicant's work. I've heard technical writers declare brazenly, "Oh, I have removed all references to the company's name, and masked all the company-specific information. Therefore, I can use it as my sample because I have created it."

Please allow me to tell you a little story.

There's this old, wizened man back home in my native town. Let's call him Wajid Ali. He is the one who built the house that we live in. Why do we live in the house and not him? Because my grandfather owned the house and passed it on to my father. How could my grandfather own the house when Wajid Ali was the one to build it? Because my grandfather got the house built, Wajid Ali was only a contractor who was paid to build it. My grandfather had bought the services of Wajid Ali. At the end of the day, contractors do not own the houses they build.

Technical writers, generally speaking, are much like Wajid Ali. They are employed by others to write documents for those others. Despite all the hard work and creativity that goes into making those documents, at the end of the day it is those others who own the document, not the technical writer. It follows, therefore, that a technical writer cannot show off such documents without express permission from the document owners. The document owners have bought the document from the technical writers. This is what lies at the heart of all the stuff about NDAs and document ownership.

It is extremely bad behaviour (I am being polite, I swear) to use a company's resources (authoring tools, documentation infrastructure) to create something and show it off as a sample without seeking the company's permission first.

Oh, um, but we all may want to change jobs at some point of time. What do we do if we're asked to present some samples of our work? Two options come readily to my mind:

  • Ask the document owner (present employer, contracting agency, whatever) for permission to use what I've created as samples.
  • Create my own samples, in my own time, using my own resources.

:) Like I read in my very first book when I was a child of not even five years (yep, I started early) - পরের দ্রব্য় না বলিয়া ল‍ইলে তাহাকে চুরি বলা হয় | যাহারা চোর, তাহাদের কেও দেখিতে পারে না | (Translation from the Bengali original: Taking another's object without telling that person is called stealing. No one loves a thief.)

Saturday, October 4, 2008

How to write badly

This blog post appeared in a slightly different form in TechCraft, an electronic periodical distributed free of cost to the members of the Yahoo group technical_writers_india. To subscribe to this group, send an email to technical_writers_india-subscribe@yahoogroups.com
In this blog post, I list some pointers that help you be a bad technical writer. Each of these instructions is followed by an example, and my thoughts on the example, but not a conclusion. This list is by no means exhaustive but I am limiting myself to the following nine because I can illustrate each one of them with real-life examples.

1. Practise anthropomorphism; empower the object

The YSQT database is a repository that:
  • Has normalised data of more than one project, location of time period
  • Lets you create trend graphs for more than one project
  • Lets you create financial reports across more than one financial period

If the software has the power to let you do stuff, it is evidently an animate object. Really? Does the software let you do stuff, or have you (or another person) let the software let you do stuff?

2. Ignore the grammar; don’t write for a Nobel

JaneDoe

The person in the picture begins with "This is Jane Doe", a sentence in the third person. Grammatically, a third person is a third party . But, there’s only one person in the picture. Where is this third party, this Jane Doe? The person in the picture goes on to say, "I will walk you through this…". So, what will Jane Doe do, and why was she introduced? Or, is "this" a demonstrative for both "Jane Doe" and "tutorial", and, therefore, refers to a tutorial called Jane Doe, and the lady in the picture is going to introduce Jane Doe, the tutorial, to us? I'm confused.

3. Ignore the dots and curls; let others figure out the punctuation

Click only once on all the go buttons. Once you click certain characters get added to your password just IGNORE.
Punctuation separates the elements of a sentence from each other and clarifies the meaning . The second sentence is wholly lacking in any such pointers and is open to multiple interpretations.

4. Use as few sentences as possible; make people read everything twice

In order to obtain the maximum benefit from the YSQT financial application, you need to have obtained the necessary license key as a paid user, which lets you gain access to the advanced features of the software, including the ability to send alerts to a specified cell phone number.
Is there a law against using short sentences? Is there a law that forces writers to lift stuff, verbatim, from the SRS document?

5. Introduce jarring notes; disturb the symphony
The properties of the YSQT word processor are listed below:
  • Easy text entry, formatting, and editing
  • You can import your WordPerfect, WordStar, or MacWrite files
  • Check for grammar and spelling
When I see a sentence followed by bullets, I expect that sentence to flow into, and weave in and out of, the bullets. For me, things fall in place faster if they are synchronized.

6. Hop, skip, jump; introduce others to agile reading
To print the page on the shared printer, follow the steps given below.
  1. Select File > Print > Page.
  2. Ensure that you are logged in to the YSQT domain.
  3. Ensure that the shared printer appears in the list of printers configured for your machine.
  4. Click OK.
When they teach us to program, one of the first things they teach us is to draw flowcharts. Going back even further in time, before they teach us to spell words, they teach us the alphabets.

7. Ignore the style guide; add variety to life

Click Next to advance to the next page. To go to the first page, click First. Clicking Previous takes you to the page you viewed last. If you want to jump to the last page, click Last.
When I read a document, I expect it to conform to a pattern, and not fling something new at me at every step.

8. Show off your hard work; put a picture on every page


The pictures do not add anything to the text. They merely repeat what is stated, and take up space. By contrast, this Google Chrome documentation is a fine example of pictures speaking a thousand words.

9. Rely completely on the software spell-checker; don’t check for yourself
To get help on the filed, lick the help icon to the right of the field.
If you run an automated spell-check on this sentence, you'll get a clean report. Need I say more?

Wednesday, October 1, 2008

Of dots and curls - Comma blurb

There was this boy called Commah,
Who was so very prim and propah,
He'd never sit next,
To an uppercase text,
Unless it was a proper Nounah.