Technical Writer

My working life revolves pretty much around Microsoft.  Over 90% of my work is done in either SharePoint or Word.

Microsoft has a lot of information on their sites about these products.  Unfortunately, I can never find it. I usually only know it’s there when I stumble on it months after I really needed to know it.

Their sites look good, and once I know what I am doing I can see that it also contains truly valuable information. The only problem is, when I don’t know what I am doing I have no idea how to actually use the information that is there.

The steepest part of the learning curve is at the start.

I really struggled with SharePoint until I learned one simple basic fact. There are two programs. Until I grasped that there were two programs, that one sat on top of the other, and that they both did slightly different things, I was forever trying to do things that wouldn’t work. For example, I read in the SharePoint Help, and in online forums, about how you could set document or list level security.  I was using SPS 2003, and I tried and tried, and I could never do it. Because you couldn’t, in SPS 2003. All the instructions were for WSS,  but because I had not yet grasped the two-program thing, I thought they were just talking about SharePoint as a whole.

Likewise with another program I use occasionally—DITA. DITA is an xml schema used for writing documentation. I’m fine with the concept of a schema. I know quite a lot about DITA now, and can write pretty much anything using DITA schemas now if I want to.  But have you ever tried to set a DITA system up on your own PC? The DITA Open Toolkit gives you good information. They even tell you how to set it up and give you the files to download. Even so, I am still on that slipperly steep slope right at the start—how do I set it up on my system, what do I need to do to make it work?

A total beginner has different information needs to an experienced user. The experienced user needs exact technical detail about specific items. Point them to the right place and if it’s organised in any logical sequence they will find what they need. 

The beginner doesn’t know the information exists, they don’t know where to look and they don’t even know what to look for. They need big picture stuff, but the things that trip them up are not even always about the system itself. With DITA, for me, it was setting DITA up to use. With SharePoint I knew more than enough about libraries and lists before I had any real knowledge of how to use them in the business. And, as I said, the two program thing was a big knowledge hurdle.

Our company intranet is a SharePoint site. I am the SharePoint administrator at my workplace, which effectively makes me the intranet administrator as well. Thus I was interested to see Jakob Nielsen’s 10 Best Intranets for 2008, and some of the comments he made about intranet design.

Neilsen says that in general intranet sites are better and more consistently designed. Single sign-on is important. (I absolutely agree with this one. If we hadn’t tied SharePoint to our Active Directory I am sure usage would drop by easily 50%.)

There was a focus on productivity. i.e. On making it easier for the user to do things.

Most of the intranet sites are content managment systems. They used a diverse range of platforms. The ten winners used 41 different products between them. The most used products were SharePoint and the Google Search Appliance, with Red Hat Linux, Lotus Notes and Domino, and Oracle databases also used a lot.

Trends Nielsen noted were:

• Increased personalisation
• Integration of information sources, often resulting in a single “one-stop shopping” page
• Emphasis on mission-critical applications and information (such as sales targets)
• Improved event and project calendars
• Special sections to help orient new employees
• Prominent display of stock quotes and other financial information
• Integration of external and company news, often in the form of customizable feeds
• Integration of alerts with the main intranet to inform users of important messages
• Redesigned and improved search features, which often went from horrible to good and generated ecstatic user feedback10 Best Intranets of 2008, Jakob Nielsen.

This is the second report on intranet’s that Nielsen’s group has produced in three months. In the first report, Intranet Information Architecture, he says that to provide a consistent user experience, when designing the intranet you should:

• Decide to proactively design the IA instead of letting it evolve
• Ensure that management supports the central Information Architect designer’s authority to provide guidance and structure to other departments’ intranet work
• Ensure that management won’t second-guess the design team and impose the awkward structures or navigational terms that individual executives happen to like.Intranet Information Architecture, Jakob Nielsen

If creating the intranet is outsourced, then the three points above happen automatically. It seems that when the job is done in-house, however, they do not. These are basic common-sense design issues that we all know, and often, the very same people who would ensure that the above three things happened on a project they were running for, say, software that was going to a customer, totally lose it when it’s the intranet, rather than an external product.

When we set up the original design for the SharePoint intranet at our work the Managers insisted on team-based areas, even though we tried to talk them into task-based. Some of it was politics. I don’t think any business unit likes to think they take a lesser position in the company than any other business unit, and often organising by tasks means that one or two groups take up more intranet real-estate than others. We have gone through multiple restructures since, and then we have to rearrange sub-areas on the site to suit the new organisation. Thank goodness it’s SharePoint, where the URLs don’t change when we move them. The managers also insisted on some weird security settings for the various team sites, the legacy of which we are still dealing with today. To be fair, at the time SharePoint was new, we weren’t aware of how it worked, and many people were worried that so-called ’secure’ data could now be changed by anyone in the system.

Intranet design has always been the poor relative to web design. It’s good to see people taking it seriously.

Today I had a frustrating experience with some software. The cause was simple, and fixing it was easy too—once you knew how—but the problem should never have happened in the first place.

It was a simple error. A web-based performance management system where you had to type in achievements you had completed in the last six months. I filled out the form and clicked Save. Save appeared to work, the system went away and did what it had to do, and moved on to the next page. It was only by chance that I went back to the page later to make a further update. And what did I find? None of my changes had been saved.

I had probably spent twenty mintues typing up what I wanted to put into these fields. Twenty wasted minutes. I put the information in again. Not quite the same detail, because obviously I didn’t think about it as much this time around, and clicked Save again. Save appeared to work again, but still nothing. My edits were not going through.

I tried a host of different ways to update the field, to no avail. I tried the user manual. It was totally useless. One of those frothy, light things full of marketing-speak that said how wonderful the product was, but didn’t tell you how to do anything. 

Finally, I called the one person in the company who knew the system well.

“Did you put a value in the … field?” she asked.

Well no, I hadn’t. The field had not had a value in it before. It did not appear to be important, and the system did not complain because I had put nothing in it. Why would I even think to complete that field?  But, sure enough, I put a value in that field and everything worked fine.

I wasted nearly two hours finding this out.

Multiply this by everyone in the company, because everyone had to complete the same form. That’s a lot of wasted time. 

This, to me, is a bug that needs fixing pronto. It’s a tiny error. On a web based system a temporary fix could have been implemented by any of the following:

• Adding a note to say that this field was compulsory
• Adding a validation for this field
• Providing a decent user manual that actually explained what you had to do for that task.

But allowing the user to fill in the whole form, and then rejecting it without even giving them an error message—that’s unforgivable.

It’s official. We’re upgrading SharePoint Portal Server 2003 to MOSS 2007.

Hooray!

This is not just an opportunity to upgrade to a better system, it’s also an opportunity to undo some of the mistakes we made first time round. It’s a chance to resell the good points of SharePoint.

Mistakes we made

Most of the mistakes we made were due to inexperience. It’s only now, after we have used the system for two years, that we actually understand these were even mistakes.

• We did not know what SharePoint really was, or what it could do
• We tried to make it too much like a traditional web site—which led to a heavy reliance on putting web parts on pages rather than sending users to content
• We used the portal server almost exclusively; there are only two ‘real’ WSS sites on our whole system
• We used SharePoint out of the box, with no customisation except for the CSS redesign
• We did not understand the concept of shared authoring well, and we tried to make it too safe
• We did not understand that SharePoint Portal Server and Windows SharePoint Services were two separate programs.

System limitations

We had other issues when we first implemented SharePoint, not related to our implementation. One of these was that at the time we were also in the middle of upgrading from Office 2000 to Office 2003. If you are an early user of SharePoint you will know just how little you could do with Office 2000 compared to Offce 2003. We went for the lowest common denominator in training, and if you couldn’t only do something in Office 2003, we didn’t show people how to do it initially. A bad mistake. By the time everyone had upgraded to 2003 habits had set in. The majority of our documents are still created on the LAN drive, for example, and uploaded to SharePoint, rather than saved directly to SharePoint.

Experience helps us sell

Three years on we also know what is important to our users.

First time around we were selling the idea of the product. “Wow. Look at this great new product called SharePoint. It has libraries and lists, and web parts.  Aren’t they great? And what about those meeting workspaces? Why don’t you set up meetings with meeting workspaces? Or sites for projects?” And the users said, “It’s too much work. And besides, I have a process that works anyway. Why should I change?”

Now we don’t bother. We lead them gently, and pretty much ignore the marketing blurb about all the impressive things you can do with the product.

Now it’s more, “You know all our policies and processes are on SharePoint, but did you know you don’t have to upload the document every time you want to change something. You can change it direct in SharePoint. Not only that, you can keep a record of every change. Look, here’s how.” Or maybe, “I see that you do most of your work from that page. Did you know you can add a link to the home page by adding a My Link?” Or, “You want to find something on a LAN drive? Use SharePoint search.” And the users go, “Wow. I didn’t know it could do that.”

Baby steps, but they have helped us far more than trying to sell all the advanced features of the product.

We’re not implementing a new product, we’re upgrading

We’re not the only ones who have learned about SharePoint in the last three years. Our users have too. This time we’re not implmenting a new product. They understand how it works, how to move around, how to add documents and even web parts.

Last time around people had to learn a new system, as well as new ways of doing things. Now they know the system so this gives us far greater scope to introduce some of the more impressive features that confused people before.

I’m looking forward to that.

To remain employable, and to continue to earn good money as a technical writer, you must keep up with technology, which changes oh-so-fast in this business.

Given that for many of us the new year is a time to make new resolutions, and often one of those resolutions is to get a new job, I thought I might predict where I think technical writing is heading this year and some areas where maybe the jobs will be better and more interesting. Here are my thoughts. We’ll see at the end of 2008 how accurate I was.

Content management systems are already here, and they’re here to stay

Repeatable, reusable content. You can’t beat it, and it makes your work so much faster and easier—once you know what you are doing. Unfortunately it’s takes effort to get used to and the learning curve can be quite steep, especially if you are teaching yourself. Stick with it. There aren’t a lot of people out there who do it well yet.

I see a time in the not so distant future where all data will be in databases, and we will pick information we need out of the database.

Larger enterprises will use more programs like SharePoint are being used.

XML has also arrived

XML is another thing that has been ‘coming’ for years, but when even Microsoft offers a ’save as xml’ option in their Office programs you know it has well and truly arrived.

Early adopters of XML spent a lot of time tinkering with the XML itself. I forsee that programs like StyleVision, and even future word processors, will hide it from us tech writers, so we won’t even realise it’s XML. Even so, you should at least know what XML is and what it looks like, and learn about schemas and transformations.

Know what DocBook and DITA are, even if you don’t know how to use them.

Media is in … sort of, and Flash rules the demos

A few years back everyone was touting online training as the way of the future. It seems to be swinging back the other way at present, with more instructor-led inside a company and e-learning for everything else. The online training has become very sophisticated—tutorials, simulations and animations. It is more media-oriented, with videos and voice overs.

Everything seems to be Flash or a combination of Flash/XML. Think some of the Mosaic Company’s animations and simulations or Microsoft’s Office training modules where you get to practise in the program.

It’s also all web-based. I haven’t seen training outside a browser in a long time.

Sometimes e-learning is like making mini-movies. In fact, I have seen a couple of advertisements lately for storyboarding e-learning modules.

Webinars

I see a lot of webinars too. Some—like Altova’s—provide instructor-led training, while others—e.g. some of the SharePoint webinars—are more to provide information.

Good writing is not the only skill you need

This is not new, but it’s worth repeating.

Being able to write well is important, but project management and people skills are equally as important. The ability to give the customer what they want, to work to deadlines, to manage your time and all those other project-related issues may make a big difference between you keeping your job or losing it to someone who can. There’s a downturn coming (or so most people expect), and this means lots of people will be after the same jobs. Good writing is only one of the skills you need to ensure you remain employed.