Technical Writer

If you’re a tech writer and you’re in Melbourne in early May this year, I highly recommend the Australasian Online Documentation and Content Conference (AODC).

I have been to a number of them now and find great not only for keeping up with what’s new in the field of technical authoring, tools and techniques, but also to meet other technical writers.

As a sole tech writer in a company you can sometimes wonder if you’re the only person on the planet who does this job.  Three days of talking to people who face similar work issues to me makes me realise I am not alone.

Whenever I meet other SharePoint users I always want to know what works for them.

Here’s what works in our company, and what doesn’t.  We use SharePoint 2003.

What works:

• Document libraries
• Revisions
• Issue lists
• Task lists
• Link lists
• Portal listings
• Office integration (sort of)
• Export to spreadsheet
• Web part pages
• Custom lists
• My links
• Surveys
• XML web parts.

What doesn’t work:

• Discussion boards
• Email integration
• Calendars
• News
• Check in/check out
• Alerts
• My Site.

We don’t use:

• Form libraries.

Document libraries

At least 80% our our SharePoint usage is document libraries.

It’s a constant struggle to restrict the number of libraries, particularly in Portal Server (SPS).  People want to create multiple sub-areas with a separate library for each, even when they would be better suited using one sub-area and one document library with folders and custom fields.  It’s a mindset thing.  Because Portal Server looks like a hierarchy, people can’t see any other way to use it except as a hierarchy.

Early on in our SharePoint implementation I let one group convince me they needed separate libraries for each type of process. 

Bad mistake.

They now have around 30 libraries, each in a separate sub-area, containing an average of three documents per library. 

In their defence, they maintain them beautifully, but it must be hard work.

They had a spring clean of processes just before Christmas. I tried to talk them into putting all the documents into one library, with customised fields, but they didn’t want it.

Revisions

People like and use the revision functionality.

Unfortunately, many people still persist in renaming major drafts and moving the old one to a sub-directory in the library.

We have been caught out a couple of times on this, because revisions are tied to the document name, and the document name is tied to the location.  As soon as you change the document name, you lose the revision history.

This one is a matter of training.

Document workspaces created through the document

SharePoint allows you to create a workspace for a specific document. You can work on the document in the workspace, add all your reference material and notes there, and when you have finished check it back into the parent library.  A fantastic tool, but we don’t use it.

Our document libraries are heavily customised—fields, names, etc. To date, I have not been able to create a sub-document workspace from anything except a standard ‘Document%20Library’ with no customised fields.

Some of our project users would love this functionality.

Check in/check out

This is another training issue.  If we don’t train people to use it, they won’t, and even then they’re unhappy about it.

Users expect write protection to work like MS Office.  When you open an Office document from a shared drive it tells you if someone else has that document open, and asks if you simply want to read it, or be notified when they have finished.

SharePoint doesn’t do this.  If two of you open a non-checked out document and update it at the same time, one person will overwrite the other one’s changes.  (Excel does say there is a mismatch.)

Email integration

Outlook rules at our office.  I would say it is the single critical piece of software people in our workplace must have.

Nobody, but nobody, uses any email/email functionality in SharePoint with the exception of:

• Two regular meeting workspaces I set up for monthly meetings
• Email alerts on issue lists.

Discussion boards

Discussion boards are an abysmal failure.

We have tried to wean users away from email on to discussion boards for technical and project discussions.  It has not worked.

I don’t really know why, but some of the reasons may be:

• Email is more immediate and less formal
• It is also more private, or appears so, anyway, even when you are (accidentally or otherwise) emailing the whole company
• We don’t have enough people. Discussion boards seem to need a critical mass to work
• Old habits die hard/resistance to change.

I would be interested to know what percentage of discussion boards overall, even outside SharePoint, succeed.

Form libraries

One potential killer application for SharePoint, in my opinion, is forms.

Our company chose not to implement InfoPath, so we do not use form libraries at all.

Such a pity.

Web part add-ins

There is no budget for SharePoint outside of the product itself.  If there was I would implement, in this order (and remember I’m talking 2003 here, not 2007):

• InfoPath
• A workflow (e.g. Nintex) 
• Rollups (e.g. CorasWorks)
• Wiki (e.g. Neoworks)
• SharePoint 2007.

Some of the free web-parts we use regularly include:

• Carlos Segura Sanz’ Cseg rollup, and
• Microsoft’s Office web components (not sure if you would call this one an add-in or not, or even free).

Overall usage 

We use SharePoint Portal Server (SPS) for most thngs, but that was more because of the way we implemented it, and our early knowledge.  People also like things displayed on the page, rather than having to do the extra clicks to go in to the content.

If we had to do it all over again it I would put a lot more into WSS sites. End result would be 50-50 SPS/WSS.

I have had some interesting conversations with writer friends recently about the concept of writing for hire, and associated copyright issues.  Some friends are quite passionate in their opinions—writing for hire is evil, and you should never do it. If you can’t retain the copyright, don’t do it.

It has never been a problem for me, as most technical writing is writing for hire.

So why do people get so het up about writing for hire?  And what is it, anyway?

What is writing for hire?

Writing for hire is when you get paid to write something—a user manual, a speech, on-line help—and the company, or person who employs you, retains the rights to that work.  That is, they own the copyright and any royalties that might ensue.

The person or company you wrote the material for can do what they like with or to it (depending on the contract you signed with them, of course). You have no say in it.

Payment may be a flat fee, an hourly rate or whatever.

It is different to ‘regular’ writing (and by ‘regular’ here I mean the standard, accepted view of writing that most people have) in that you, the author, do not retain the copyright.

And that’s why so many people hate it—because they don’t own the copyright.

So why do it?

Because it’s a job.  It pays well.  Why not take a job that allows you to do what you love (write) all day, every day?  It’s fun.  How many people can say they get paid to do something they enjoy?

Not only that, the copyright is generally useless to you. Who is going to buy your “How to Use Warwick’s Widgets” except Warwick? 

What’s all the fuss about then?

The problem comes about because some people believe that whatever they write belongs to them—always, no matter what. 

It doesn’t.

Standard copyright law says, yes, you own the copyright to anything you write.  However, you will find that when you take a job as a technical writer you will be asked to sign a form to say that anything you create as part of your work for that company is theirs, to do as they wish with.

When I take work like that I read the form carefully to ensure that is the only thing they get to own, and then sign it. 

Note: By ‘only thing they get to own’ I mean they have no control over other writing I do, like this blog, or my novels, or other technical writing I may do for other companies at the same time, or any time in the future.

Friends who are so passionate about the importance of retaining copyright tend to be:

• Novelists, and/or
• People who do not make their main income from a writing-related job

and most of their aversion to work for hire comes from novelisations, rather than technical writing. 

They cite cases like that of Carolyn Davidson, who created the Nike swoosh, and how she was paid $35 for a logo that went on to become one of the most recognised symbols in the world.  (Yes, I know it is not writing, and one is copyright and the other a trademark, but the principle is still the same.) 

Sad to say, it was a work for hire, and all Davidson was really owed for that logo was the $35 Nike paid her. They were under no obligation to come back later and give her Nike stock as well, which they did.

As writer Mel Gilden, who wrote novelisations of the 90210 television series says:

… What, if anything, am I getting out of it? The trivial answer, of course, is that I get money. 90210 paid my bills for many months.

“Are Novelizations the Scum of Literature?“  Mel Gilden

While I do not advocate that you should ever give away copyright of a novel you have written, I would be perfectly happy to take on a novelisation as a work for hire, and look on that as almost just another form of technical writing. 

If the book company later made millions out of the book then so be it. It was my call, I had the choice to write or not write, and I took it on as a paid piece of writing work.

It’s your choice

Novelisations aside, because obviously that’s just a small sub-set of writing for hire, if you believe so strongly that you should never write for hire, then don’t.

It’s your choice.

Just don’t expect much work as a technical writer.

The Dummies series of books are a writer’s dream.  Clean, well written, with personality and an easy read.  Perfect as both a reference and as a learning tool.

I flicked through Digital Photography for Dummies over the weekend.  Very nice.  My business partner, Calder, also recommends QuickBooks for Dummies. Yet the only Dummies book I ever read was C++ for Dummies, and I confess I didn’t read much.

My C++ was rusty.  I had spent two years coding C++ at university but hadn’t touched it since, and then I had to document code written in that language.  I bought C++ for Dummies as a memory jog.

I never finished the book.  I couldn’t understand it.

The author constantly referred back to how things worked in C, which I had never used. It totally lost me as a reader and I didn’t bother to read more than a couple of chapters. I will never know how good the book was, or wasn’t.

Comparing new programs to old ones works for a cutover period, when the bulk of people using the new program are converts from the old, but it becomes really frustrating after that, even to these converted users.

Microsoft has just released (or is about to release) Office 2007, and I imagine this will bring on a rush of cross-over books, which is fine, but for how long are they needed, and what do you do with them after they are finished?

A lot of cross-over information will be posted on the word wide web and on intranets.  A lot of it will stay there long after its use-by date.  They gradually disappear, but even now the occasional Google search brings up instructions on how to do something in Office 2003 compared to doing the same thing in Office 95.

A lot of the cross-over material gets forgotten.  I recently looked at some old “Introduction to SharePoint” CBTs I wrote for our implementation of SharePoint as an intranet, and realised that some of these modules still referred to ‘how we will do things in our new system’, even though we have been doing it this way for two years now, and over 50% of our current staff had not even been working at the company when we implemented it.

When do you know it’s time for the cross-over material to go and how do you keep track of what has to be changed?

Maybe there’s another way to do it.

Microsoft have introduced the interactive: Word 2003 to Word 2007 Command Reference Guide which allows you to choose a menu option in Word 2003 and then shows you how to do the same thing in 2007.

I really like this, because I am not good at remembering the names of commands. 

If I want to change a style I know which menu I have to go to, and which option to click on when I get to that menu, but if you asked me how do do it I wouldn’t be able to say, “Click on the Format menu, and then choose Styles and Formatting.”  I would have to check it and do it.

Using a tool like the Word 2003 to Word 2007 Command Reference Guide I can re-write procedures totally in Word 2007, but for those people who already know what to do in Word 2003, I can just provide a link and say, “Go to it.”

Later on, when everyone is familiar with Office 2007, I can remove the link.

It’s much tidier, and a lot easier to manage.

In a recent blog about the Ugly in SharePoint 2007, Tom Johnson asked about RSS feeds in SharePoint, among other things, and I replied with a rather lengthy comment that said although I hadn’t used SharePoint 2007, what I seen so far, and my experience with SharePoint 2003 led me to believe that it wasn’t going to be much use to the average office worker.

But it got me thinking, so after that I went back and looked at the RSS feature again, and now I’m not sure I was right.

Especially after two workmates who looked at it with me—both fairly ambivalent about SharePoint to date—said they liked the default RSS option that came with the list.

They’re both spreadsheet people. Normally their first instinct with any list is to export it to a spreadsheet.

In this case, they saw the RSS feed simply as better way to display the list.  While here I am, still thinking about traditional RSS feeds—gathering information from one location to display elsewhere.

So I was wrong about RSS feeds.  It is my thinking that needs to turn a little to truly see the value of it. 

The really good thing about SharePoint 2007, though, is that thre is enough improved functionality to make someone ambivalent about SharePoint 2003 sit up and take notice.

That’s a great selling point.