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.

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.

In SharePoint, we are likely to think of developers as people who work to customise SharePoint, but there are a lot of developers out there who are simply end users of SharePoint. How do they like the system?

Everyone has preferred software, tools and working methods they like to use.  For me, it’s:

• Dreamweaver over Front Page (now SharePoint Designer) any day
• XML Spy as the best XML tool
• Never write code when XML and an XSL transform can do it for you.

Some of these are preferences I have garnered over time working with the tools. Others are just habit.

I always use Word, for example, to create lists. My business partner uses Excel.  My business partner trades shares. She records the the trades in a spreadsheet. If it was me, I would use a database.

I work with developers. While individual developers differ, I think that the majority of them would say:

• Unix is better than Windows
• Open source is the only good software (except for the code they write, of course)
• Mozilla Firefox walks all over Internet Explorer
• Visual Basic is not a ‘real’ programming language
• If Microsoft made it, it stinks
• Wikis are the only suitable tool to share information.

It’s the last point I want to address.

Wikis are useful, yes, but you can share knowledge outside of wikis.

As part of my job I coordinate the technical reference material for the developers at work. Every so often one of them tells me about a new wiki or content management system they hear about.

I look at the specs—I am always interested in things like this—and I think, “We can do this already in SharePoint, and we can do that, and that too.”

In short, every one of the features available in most wikis and content management systems is already available in SharePoint, which is the system we have and use at work. And we’re only using SharePoint 2003, we’re not on 2007 yet.

True, SharePoint is somewhat clunky, and despite the fact that you can do simple things almost immediately it does have a steep learning curve, particularly if you want to get the best out of it.

Developers use SharePoint in two ways, depending on their job.

• If they are SharePoint .NET developers then it’s their job to work with SharePoint. They know it well and know what it can do.
• Or they can simply be end users, using SharePoint to access information in the same way others in the company do.

End user developers have a natural aversion to using SharePoint. It’s a Microsoft product, therefore instantly suspect. It’s complex. Life shouldn’t be that hard. They don’t get a chance to get under the hood to do fun things they would like to, like writing web parts. Not to mention the one huge minus—Firefox and SharePoint don’t play well together.

I work with end user developers. Right now they use SharePoint as little as they can. Other users in the company must use SharePoint. Work procedures and other work related information is listed there. It has links to other systems that they use. But the developers … they can bury themselves in the code and only visit the portal when absolutely necessary.

Like every other IT department I know we’re always busy, but I keep trying to convince the powers to let me run some lunch-time sessions for developers on how to write web parts. I think if they knew more about the system they would be happier to use it, not to mention improve their future job prospects.

So far, I haven’t convinced anyone to let me do it.

Our SharePoint portal server (SPS 2003) has a corrupted search index. As a result I have learned a lot about the SharePoint search database in a very short time.

First up, even though SharePoint itself is managed in a SQL server database, the search database is not SQL. It is what is known as an Extensible Storage Engine, or JET Blue database engine.  To quote Wikipedia:

The Extensible Storage Engine (ESE), also known as JET Blue, is an Indexed Sequential Access Method (ISAM) data storage technology from Microsoft. ESE is notably a core of Microsoft Exchange Server and Active Directory. Its purpose is to allow applications to store and retrieve data via indexed and sequential access. Windows Mail and Desktop Search in Windows Vista operating system also make use of ESE to store indexes and property information respectively.

Wikipedia, Extensible Storage Engine

(fyi. There is also a Jet Red database engine. This is the database Microsoft Access uses.)

The database itself is stored on under the c:\program files\sharepoint portal server\data directory on the computer that runs SharePoint.

At work we have around ten SQL experts, and probably another 20 people who are really comfortable with it.  But finding someone who knows about JET Blue is another thing altogether.

The corruption of the search database has somehow spread to SharePoint itself, so that we can’t even delete the it from SharePoint. Right now all I want to do is get rid of the whole search database and start again.

The most frustrating thing is that Windows SharePoint Services (WSS) search still works perfectly.

[nb. We are running an SPS 2003 site, I don’t know if they are using the same type of database for MOSS 2007.]

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.

An anti-Microsoft rant.  Unusual, because I like their products and 90% of all the computer programs I use are Microsoft.

Here in Australia—and I believe the rest of the world—Apple are running a series of Mac vs PC ads.  Most of us have seen them by now.  One in particular really resonates, the one that has a go at the overly intrusive security system on Vista, which requires users to cancel or allow virtually all user actions in an effort to make the PC secure.

We have Vista at home on one PC, and sometimes I want to turn off all security because those annoying messages frustrate me.

The worst thing is, I’m not even sure where the problems really are.  Vista, or Internet Explorer 7 (IE7).  I suspect it’s a combination of both, but that makes any problem twice as difficult to track down.

IE 7 was released not long before Vista. I know I started using IE7 only a month before I got Vista.

Here are three specific examples I have personally come across, one work related, two from home.

• At work, on our SharePoint Portal Server (2003) we use Microsoft Office web components.  We have used them for over twelve months with no problems.  Users have no problems accessing them, provided they set their portal server as a trusted site.  Recently, a small number of users upgraded to IE7, and suddenly we’re having problems with web components.  If the site is not a trusted site the user gets a message warning them that someone is trying to download date, asking them to okay it.  If the site is a trusted site they simply get an error. I am sure it’s only a setting, but it is extremely frustrating.  You would think that Microsoft would have ensured their own products were compatible, at the least.
• Vista and Java.  The home PC that runs Vista blocks Java on startup.  I have to go in and physically say it can run every time.  I can see no logical reason for this except that Java is a non-Microsoft product. Few people go long on the internet nowadays without running a Java applet or two.  Microsoft knows this, so why bother to make it so hard?
• The Microsoft genuine advantage. By the time you put up with having to manually load Java, and issues with programs that used to run perfectly but no longer do, you start to get annoyed with everything the company does that isn’t seamless.  This last issue probably isn’t really an issue, but compounded with the other two problems, it is really annoying me.My software is the genuine article.  Every Microsoft product is either store bought, with genuine serial numbers, or in the last two months it’s part of my TechNet subscription. Two days ago I attempted to download the Microsoft Save as PDF addin.  This is one of those products that Microsoft validates first, to ensure that you have a genuine version of Office before it will allow you to download the addin. That’s fine. I do have a genuine version of Office.The validation failed and it took two days to find out what was wrong.It turned out I had an unregistered copy of Visio on my PC.  I had loaded Visio up one day last week, but had not yet got around to entering the registration code.  You know how it goes—sometimes you get called away in the middle of things, and come back to it later.  It’s not even part of the standard Office suite.

The whole security thing is really annoying me at present. 

I am reminded of a security expert I worked with, who once recommended that I never create forms where the user had to okay alert that told them when something was happening, when those things were not errors.

“If you make them click okay all the time when nothing is wrong,” he said.  “They start ignoring the messages.  Then, if something really does go wrong, they miss it, because they’re so used to ignoring the messages.”

That’s about where I am at with Microsoft at present.  I am sick of their so-called security, which is continually bringing unimportant matters to my attention.  I am already at the stage where I ignore any messages Microsoft puts up, and all I want to do is turn the whole security thing off.

My boss used to write his own blog on our company intranet. 

It was easy enough to do in SharePoint (2003). He added each blog as a portal listing.

The blogs were popular.  He used the same chatty, informal style he used at our team meetings, and gave us the same type of news—about our team, about what was happening in the company, about where we were going with our projects.  Everyone enjoyed them.

He stopped after four posts.

I asked him why?  Was it too much work?

It wasn’t the effort of doing it, he said.  In fact, he enjoyed writing them. The problem was that people took what he said as fact, and started copying and pasting his comments as facts into other reports.

In one blog, for example, he spoke about a major project he hoped to start before Christmas.  It didn’t start until March.  He had not committed to the Christmas date in any formal report, but other departments took the details from his blog as fact.

Now you might say he should have known that would happen, but what is a blog, and what do you expect from it?

By its very nature a blog is supposed to be more informal than a standard business document.  More of a chat than a ‘real’ report.  Most people accept that.  Had this man stood in front of his team at a team meeting and told us exactly what he said in his blog, it wouldn’t have been a problem.  But this time he wrote it down.

If you are considering starting a blog at work, think about the potential consquences.  Blogs are fashionable at present, and not just in the personal space.  The CEO of our parent company even does one, although I confess it’s most of us don’t read that—it’s somewhat bland and plays very safe (with good reason).

Blogs are, by their very nature, public (even on an intranet), and the blogger has little control over what other people do with the content.  Anything in the blog is liable to be quoted, and often misquoted. It’s a hazard of blogging.  If the blog is too safe it doesn’t tell the reader anything useful. People don’t read it, and so it becomes a waste of time writing it in the first place.

Starting a blog at work is more risky than starting one outside of work.

Think long and hard about the consequences before you do so.

SharePoint’s biggest competitor is its own product sibling—the Microsoft Office Suite.

Office’s success means there is no real need for SharePoint.

Yes, SharePoint can provide added benefits, but today’s office can run without it. Take away Outlook, Excel or Word, however, and what happens?  Work grinds to a halt.

Take away SharePoint (but leave the other Office products), and people cope.  They go back to the old way of doing things, saving their file on local drives or servers.

While Microsoft lists SharePoint Server as one of its Office products, it is not one of the base desktop products that most people recognise as the Microsoft Office suite.

Nowadays most people are familiar with email, word processors and spreadsheets.  They learn about them at school. They know what each product does, and how. They are basic must-have tools to get by in today’s business and schools.

Try telling someone how important SharePoint is.  What do you say?  “It helps you collaborate with your team members.”

They say, “I collaborate anyway. We exchange emails all the time.”

You say, “Well, what about file sharing?”

They counter with, “I can use Windows Explorer to share files, and at least they’re still accessible when SharePoint is down.”

Ouch.  Because you know everyone remembers the times SharePoint goes down and their documents are inaccessible.

Anything you say can be done via SharePoint can also be done in another Office program. Issue lists—you can do that in a spreadsheet.  Tasks—you can do that in Outlook, if it’s your personal list, or a spreadsheet if it’s a group list.  It seems you can’t win.

The thing is, these people are right. Excel spreadsheets and Outlook mail are good tools.  Why bother with SharePoint when you already have something adequate for the job?

I’m having more fun with my TechNet subscription than I expected to.

It’s a 12-month subscription to pretty much every program Microsoft.  I purchased it because our work has decided not to upgrade to SharePoint 2007, nor to Office 2007, and I need to keep up-to-date with the technology. I am planning on moving on some time (hopefully this year).

I haven’t got around to installing SharePoint yet.  So far I have only installed the standard Office programs but it has been good to learn about each of the new versions. 

I know I could have run the trial version versions, but these are full versions and I don’t have to worry about time limits.  I can also test out various programs that I wouldn’t otherwise touch, like Groove.  (I still haven’t figured out where Groove fits in.  I mean, isn’t it doing similar things to SharePoint, only off-line?)

It’s not cheap, but it’s value for money if you intend to use the full suite.