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.

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.

It’s my job to document the system.  Most times that works fairly well, but every once in a while you come across someone who’s determined to do it all himself.

I’m working with one of those at the moment.  He has a major piece of knowledge he needs to transfer to others in the team.  He wants to do it all.

No matter that it’s my job, that all I do all day is write about the system. No matter that he has to do other things, like coding, 40 hours a week (except for the bit where he’s supposed to hand over knowledge to me so that I can write it up for him).  No matter that he’s flat out on projects that must be completed for the next software release. No, he insists on doing everything.  Setting up a training course, writing the material, running the demos.

Worse, he’s not even doing it in the standard format I have already set up for knowledge transfer.

This guy has some really good ideas.  I like what he’s trying to achieve.  However, I can’t just sit back and let him do it.

First of all, I’m fairly sure it’s not going to happen.  He has a full schedule even without this work and we tech writers know from experience that the first thing to fall by the wayside when a release is behind schedule is the documentation.

Secondly, there is no need for him to do it.  He has a perfectly good resource—me—sitting there waiting to do it for him.  All he needs to do is spent a tenth of the time he otherwise would, transferring the knowledge.

Lastly, I can’t let him do it because we can’t afford to let everyone loose with their own way of doing things.  We already have a process for doing and presenting technical documentation.  It may not be the best, but it is consistent.  We don’t want people to learn a whole new system.  We want them to use the one they are familiar with.

There is only one way to deal with people like this.  Carefully.

You need to keep them on side and working with you, but you also have to somehow wrest control of the project away from them and get them to accept that you own it, and that they are doing it your way—or rather, the same way everything else is done.

Take on board their ideas, by all means.  Do some future planning with the really good ideas and try to fit them in to the overall training/knowledge strategy if you can, but don’t let them do their thing.

That’s a lot easier said than done.

I took the plunge and installed SharePoint 2007 on my home PC last night.

As my home operating system is Vista, I installed a virtual PC first.  (Easy enough to install, using the instructions from Microsoft.)   After this I installed Windows Server 2003, then SQL Server 2005 and finally, MOSS 2007 on top of that.

It wasn’t too hard, although it took all day.  I had two sets of instructions to follow.  I used SharePoint Reporter’s How to create a MOSS 2007 Virtual PC: The Whole Nine Yards, with Eli Robillard’s How to Build a SharePoint Development Machine as a reference, particularly for some of the Virtual PC settings.  (Robillard used a different virtual PC, which is why I didn’t use his instructions, but they were both similar.)

The instructions were a dream to use.  They told me exactly what I needed to do, and when.  They were everything good documentation should be.

Although I had never installed Windows Server or SQL Server before, I had not trouble setting it up.  There was enough information to carry out each task, but there was no unnecessary clutter in them either.

Everything was exactly where I needed it, when I needed it.

I ran into difficulties right at the end, after MOSS 2007 had been loaded, but I suspect that had more to do with the fact that I went out to dinner with friends part way through installing SharePoint and tried to finish the install four hours later, after a civilised amount of wine had been consumed.  Still, I was on familiar territory then, so I ditched the instruction and winged it.

I started at 10:00 am, and finished at midnight.  None of that time was spent troubleshooting, it was all spent following instructions and waiting for installs—and dinner, of course.

That’s a pretty impressive piece of documentation.

Over at I’d Rather Be Writing, Tom Johnson wrote about how  watching a user follow your instructions was one of the best writing tips ever.  Tom wrote about how the user scans and glances, rather than reads, and how you really need to simplify the words so that the user doesn’t have to read.

It was not long after this that I had to find out how to create views in InfoPath, so I went along to Microsoft’s site and found the training module So that’s how: Great InfoPath features for customizing controls. 

[Just an aside here. I don’t know how I found it the first time, because I unwisely failed to bookmark it and have just spent half an hour (that’s right, 30 minutes) trying to find the link again.  Most frustrating.  I didn’t think to look for Great InfoPath features for customizing controls. I was searching for views or buttons or dates, which I knew it covered.  I don’t know about you but I seldom find anything direct in the Microsoft site itself. I always have to use an external search engine, such as Google, to discover things.]

Anyway, I found the tutorial, and it’s pretty good, as are many of the tutorials on the revamped Office site, if you can find them.  Each section contains introductory audio/visual text, which you can read, and then allows you to switch to the program where you can follow the instructions to learn how to carry out whatever you are being taught.  Afterwards, you got a quiz with simple questions to cover what you had learned.

I skipped through the introductions, just clicked Next and Next until I got to the Practice in InfoPath buttons.  As I did this I remembered Tom’s article, and how his user just scanned and glanced at extraneous information.  This was the very same thing, and I am generally someone who reads manuals and other material—but not, obviously, when I just want to learn how to do something.

The introductions were well written and well presented.  They wouldn’t have taken long to read/listen.

I also skipped the quiz at the end of each section. Again, they were well done, but I just didn’t bother.

I was a standard user in action.

---

p.s. Funnily enough, after I had written this blog, but not posted it, Tom posted an article on another of the Microsoft tutorials—A perfect model for online tutorials: MS Visio Shapes course.  I have to agree with him.  These are good models for online tutorials, both the Visio and the InfoPath one.  If I had designed and written these I would be very happy.   

Back in December last year The Content Wrangler judged a wiki contest.  This was an American Idol style contest, where the contestants (software companies who developed wikis) got up in front of a live audience and promoted their product.

For the most part, contestants … babbled on incomprehensibly
The Content Wrangler

I bookmarked the article and go back and reread it occasionally.  A lot of the comments the author made were relevant to more than just trying to pitch software. As technical writers we tell ourselves we are ‘writers’, not salespeople, but it’s a fact of life that if you want to succeed in any business you have to sell yourself and your product.

I don’t mean that you have to be a sleazy salesman, but you do have to

sell (your) value over the others and differentiate (yourself) from the so-called “competition”

as The Content Wrangler puts it, and some of the ways he recommends you do this are by …

Preparation, or lack thereof. The vendors who participated in the contest may have decent software, but you’d never know it because they failed to do their homework. They did not know their audience. They did not—apparently—practice, at all. They didn’t know what they were selling nor why we (potential customers) would want to buy it. They mostly touted features, instead of solutions to problems. When a problem/solution was introduced, it left you wondering, “Do these guys even know what MY problems are?”
 The Content Wrangler

If you read that paragraph above you can see that the comment could just as easily apply to a job interview, or a tender for a contract.  You don’t go to a job interview without finding out what you can about the company you are applying to.  You don’t go to a job interview without thinking about the work they want you to do and how best you can sell the fact that you will be ideal for the position.

You wouldn’t tender for a contract without preparing by finding out more about the work required and how long it is expected to take.  You would be out of business very soon if you did.

Good advice.

After my mention the other day about WordPress being a good, simple content management system a colleague introduced me to Joomla.

Joomla is more complex than WordPress but it has more power.  Because it’s a real content management system—unlike WordPress which is a blog with content management capabilities—you don’t have to customise it to make it look like one.  Other people have also created templates you can use.

Like WordPress, it runs on an Apache server with a MySQL database behind it.  And like WordPress, it is open source, so it doesn’t cost.

One thing I particularly like are the setup instructions.  They’re simple, direct, and even a little bit fun.

I’ll give Joomla a trial run and let you know how I go.

We are in the process of moving our fiction-related writing over to our pen name site, http://www.rowandai.com/.  At the moment it sits as a separate WordPress blog under our work site (http://www.infinitediversity.com.au/). 

We had a long discussion about how we might do it.

Did we want to do as we had done with Infinite Diversity, where we had some base HTML pages and just linked separate blogs beneath it?  Or did we want to base the whole thing around a WordPress blog so that managed all our content from the one place?  Because that’s what WordPress is, a content management system (CMS).

I know that some users of high-end CMS’s may dispute this definition, as a high-end CMS does a lot more.  But what is a content management system really?  It is content, stored in some kind of database, accessed via a front end.  That is exactly what WordPress is.

Not only that it’s free, well supported, and easy to use.

The problem with WordPress is that it’s a blog.  It looks like a blog, and while we want to include a blog, we want the whole thing to look like a web site, not a blog.

We want our blog to blend in with the site, so if we decided to go the HTML top level with WordPress sitting beneath it route we would have two sets of style sheets—exactly the same—to manage.  Not to mention two different ways of inputting the data.

We would have to customise the layout extensively if we used it.  Neither of us know PHP, but we’re both okay with HTML and CSS.  I think we can manage the PHP component, with a little help from W3Schools and the WordPress documentation.

We decided on the single solution.  A standalone WordPress website, with customised pages to look like a blog.

Because, let’s face it, if you can get around the design issues, WordPress has to be one of the best, cheapest content management systems around.