I’ve been fairly lazy about this blog since maybe the middle of last year. It’s because I started contracting as Tech Writer for one health company and then joined another one as a permanent employee later. Now I’m seriously considering whether to continue with this website or not. Maybe I’ll make it into a Tech Writing Tips website. Pull the plug? Dunno.

Anyway. This post is related to my recent work. Where I work, I pretty much do documentation the Neanderthal way – MS Word, print out into voluminous folders etc. After writing up documentation for a couple of products, my team realized that no one wanted to read our documentation because its voluminous. Why use 10 when words when a 100 would do, right?!

So we decided to go with online documentation. Now when you’re used to creating 60 page documents and suddenly need to transition the content for online readership, you hit a snag. Online writing is stylistically different, even for something like technical writing where you think there’s not much room for creativity. I mean you’re never going to see sentences like “As he drove down the highway, towards the setting sun, he suddenly felt tired. Come, said the sun, rest a while in my arms.”

It’s pretty much all “Log in remotely into the Database server” type text – terse, to-the-point, instructional.

But even though my job is to “technical write”, I tend to give background in all my documents, such as why are you logging into the database server? What business need does this part of the document fulfill and how does it map to the software application you use to do your work. You know little nuggets that help the user not walk through it like a zombie. But I realized, much to my horror, that the details might need to be pared down.

Since we already had a Sharepoint Intranet, the expectation was pretty much that we should use some aspect of it as our online documentation repository as well.

Some research later, we figured the best way to create documentation in Sharepoint was to use a SP Wiki or a Blog. Some more research revealed that Sharepoint Wiki is unlike any other Wiki you’ll ever see. And not in a good way:

a) There’s no standard formatting controls. SP expects the browser to do the formatting. My 64 bit IE 9 browser proved useless, though I found that the 32 bit IE 9 browser supports this. Go figure!
b) Also SP Wiki relies on HTML for creating markups etc. Essentially, you’re faced with handcoding your entry, which I can do pretty well, but I prefer the convenience of an HTML editor. Which comes built into the UI in blog platforms like WordPress.
c) Inserting an image into the Wiki entry is a royal pain.

The other option was to use an SP Blog site. I found that I preferred the SP Blogs option. The IE 9 formatting toolbar issue still remains,  but SP BLog sites comes with this nifty feature that lets you use Word to do all your fancy formatting, insert any images you want and publish directly to the Sharepoint site. I also used some fancy JQuery (go JQuery!) to create sections that are expandable/collapsible, so the user doesn’t see the text unless he needs to.

(If only MS had managed to implement its Wiki line the way it implements Blogs.) But hey, Microsoft, take it one step at a time, maybe you don’t want to overexert yourself and have a heart failure or something.

I ran into some issues getting this cross-functionality between Sharepoint and Word to work, but it merits a Part II. Watch out for it.