Technical Writer

The Content Wrangler’s 10 DITA lessons learned from Tech Writers in the Trenches really nails down some vital things you should know if you want to implement DITA. More than that though, you can apply the lessons learned here to almost any project, not just technical writing and not just implementing new software.

Every time I read it I am struck by how true it is. A couple of the lessons are particularly relevant to me, particularly with SharePoint—more of this in later posts.

One of the really great things about sites like The Content Wrangler, though, is the sense of community you get from reading about other technical writers. Sometimes it can seem you’re the only tech writer on the planet, the only person experiencing the frustrations and difficulties peculiar to technical writing.

Another site that makes me feel the same way is Creating Passionate Users.

Take a look at both sites. They’re good value, and it’s always nice to know you are not alone.

SharePoint can be a marvellous project management tool—provided you let it.

In order to do this, however, you have to think about how it can benefit you, and change your processes accordingly.

Sadly, until SharePoint is well established, most people won’t do this.

Take a really simple example.

A company I know uses SharePoint Portal Server as their company intranet. On the intranet they have a social area.

Every year this company holds a children’s Christmas party. Staff members bring their children along to the party where they eat party pies, play games and meet Santa. Each child gets a present from Santa, based on their age and gender.

The social page on the intranet advertises this party. It tells when the party is on, where it will be held, and what to do if you want to bring your child along.

The company needs to know the following:

• Name of each child
• Age of each child
• Gender of each child.

How do they do it?

They send around an email with voting buttons.  Yes, I am bringing one or more children; no, I am not.

They ask you to include in the reply, the name, age and gender of each child.

A member of the social club receives the replies. They transfer the names to a spreadsheet.  They use this spreadsheet to plan catering, and to work out how many presents to buy for each age group.  They also use it to print labels for each present.

This is prone to error.

• Emails get lost in the many work emails that come through
• The parent replying may add their child’s name, but forget their age or gender
• The social club member may be in a hurry one day, and forget to transfer the name(s) to the spreadsheet
• They may mis-type the name when transferring it to the spreadsheet. Ditto the age, and gender.

It takes time. Time to set up the voting email, time to transfer the detail to the spreadshet.

So, how might we do this better in SharePoint? Remember that a page already esists advertising this event.

• Create a custom list with three columns—child’s name, age and gender. All of these fields would be compulsory.
• Create a view that only displays items you (the person viewing the screen) have added
• Add the list to the page, using the new view you have created

This is a simple list. It will take at most five or ten minutes more to set up than the voting buttons would have.

Now, copy the address (URL) of the page. Write your email exactly as you have before, but instead of asking the people to reply to your email, ask them to click on the link to the page.

Each parent goes to that page, and adds their child(ren)’s information by clicking Add New Item, and adding an item for each child. 

They can’t omit any of the information because each field is compulsory. Not only that, because the view displayed on the page only shows the children they have added, they can see immediately whether they have made a typo and fix it.

Each parent has had to do maybe two clicks more than they might have done otherwise, but that’s all.

What about the social club person?  Yes, so far they have spent five or ten minutes more creating the list, but that’s it.  And now the usefulness of SharePoint comes to the fore.

They don’t have to receive the emails. They don’t have to transpose the names to a list. It’s all done for them. Not only that, we have eliminated nearly all potential for errors.

All the social club organiser has to do is export the list to a spreadsheet when they are ready to print labels and organise catering.

They have saved themselves 90% of the work. (Not 90% of work organising the party, but 90% of the work gathering the names.) And the results will be accurate.

Unfortunately, the company mentioned is not SharePoint savvy yet. When this idea was suggested, the reply was, “But it’s too hard to set up.”

You counter with, “Yes, it may take an extra five minutes to set up, but think of the time and effort you will save later.”

They came back with, “But it’s confusing for the user. And anyway, it’s not that much effort to transfer the names from the email to the spreadsheet.”

Nothing you can say or do will make them budge.

They won’t make the mind shift.

The technical writer brings knowledge and repeatable processes to the workplace.  Once you have (good) documentation, it doesn’t matter if the person who normally does the work is sick, or on holidays, their back-up can use our documentation to do what needs to be done.

 

I first came across the term ‘hero’ back when we were setting up process improvements using the Capability Maturity Model (CMM).  [CMM has since been replaced with CMMI.]

It’s the first stage of process improvement.  You start off with ‘heroes’ who know a system or process well and are the only ones who can use it.

There are no reference materials.  If you need something done, or anything goes wrong, you call in the hero.

The work hero often sacrifices their home life in their selfless devotion to the job. Even when they are sick, they struggle in to work, because they are the only ones who can do a particular task.

The sad fact is, workplaces don’t want heroes.

No matter how much the ‘hero’ does for the company, no matter how many sacrifices they make, all their heroism does is damage the company, by making it dependant on a single point of failure.

An ideal workplace has no heroes at all.

To get past the hero stage, a company needs repeatable processes.  Processes anyone can do, not just the hero.

How do you ensure a process is repeatable?  You document it.

Who documents it?  That’s often the technical writer.  (Or occasionally the hero themself.)

Once a process is documented, the hero is no longer a hero, they’re just another cog in the workforce.  The company likes it that way.

What if you are the hero though?  You’re indispensable to the company, right?

Wrong.

A company that relies on heroes is in trouble.  If they’re any good as a company they’ll eventually drag themselves out of that trouble by setting up some repeatable processes.  Otherwise they’ll go broke.

As the old saying goes, if you’re not part of the solution, you’re part of the problem. Accept that the only long-term harm you are doing is to yourself, by sacrificing your life to the company, and do something about it. 

Here in Australia, at least, until recently there were few courses on technical writing. Those that existed were mostly 6-12 week night classes, two hours per week, or weekend classes over one or two full days.

A writing qualification was not required for a position as a technical writer.

There were two ways to get a job.

• Fall into it
• Deliberately choose technical writing as a career.

Falling into the job

Most people fall into the job.

They might know a product or system really well, for example, and start documenting it for others; maybe even running training sessions. They become known as the person who documents the system or process and gradually, over time, become to realise they are a technical writer.

Sometimes, the only way they realise what the job is called is when they start looking for their next job, using search terms like ‘documentation’, ‘on-line help’ and ‘training materials’.

For this person, choosing the ‘career’ of technical writing is often a good career move; a step up from what they are currently doing.

These people often use it as a stepping stone to bigger and better jobs.

The career technical writer

A very small number of people deliberately choose the career of technical writer.

They know that such a role exists and they actively seek it out.

In my experience, this second group comes almost exclusively from the IT sector, and almost always writes outside of work as well.

For this type of person, choosing the career of technical writer is a sideways step at best, a move into a career backwater that has little chance of advancement.

Technical writing is not going to get you a long way up the corporate ladder. Very few companies have teams large enough to offer a management career path in the field. If you want to go far, you must change streams.

While the only CEO you’re ever likely to become is CEO of your own company, it’s a great job if you choose it. You can pick your jobs to suit you (within reason), there is variety, and you get to do something you love.

Writing courses 

Over the last few years a number of courses have been introduced particularly for technical writers. 

In Victoria, for example, you can choose from courses at Swinburne, RMIT or Holmesglen. 

It will be interesting to see how the job dynamics change once the graduates from the new university courses start making an impact.