Technical Writer

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.

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.

Happy new year. 

As part of my work for the coming year I get to create a new technical reference for our developers. A technical reference is more than just an application programming interface (API) or software development kit (SDK), although it necessarily encompasses both of these. It is a knowledge base.

So what makes a good knowledge base?

It has to do two totally different things, for two totally different audiences.

• Provide an introduction and learning tool for inexperienced users. Start at high-level concepts and work through the material, going deeper and deeper, so that in the end the user comes out with a good idea of how the system works
• Provide a quick lookup for specific pieces of information for experienced users who know what they want to do, they just need to know how to do it, or what tool they can use to do it with.

It also has to be:

• Easy to maintain, and
• Up to date.

There is no such thing as a perfect design that suits everyone. A knowledge base that’s perfect for one person may be hopeless for another.

Knowledge bases/technical references that work for me, personally, include:

• W3 Schools site—I have used this site to learn HTML, Javascript, XML, XSL, CSS and SQL. Simple and basic, although I don’t know whether a non-technical person would find it easy to use
• Wikipedia—Very easy to use. Controlled totally from the search field. Even better, it’s easy to update, and updates are done by the users.

Knowledge bases that contain masses of truly fantastic information, but which totally lose me include:

• W3C—The World Wide Web Consortium set the standards for almost anything web based. If you want to know anything about HTML, XML, XSL, SOAP, WSDL—anything at all, this is the place to find it. Only trouble is, until you understand how the system works, it can be really hard to find things
• MSDN—If you want to know anything technical about any of the Microsoft products, anything at all, this is the place to come. Particularly the MSDN library. Only trouble is, unless you know where to look it’s hit and miss as to whether you find it. (I get so confused with this site, particularly with all the 2007 products coming through, that I’m not even sure I’ve given you the correct link.) I usually discover things on this site via Google search.

A knowledge base that works is one that people use.

For me, a general rule of thumb for a knowledge base that works is:

Do existing team members recommend the knowledge base as the first point of reference to new team members?

If they do then I know I am close to getting it right, because if the person inducting the newbie doesn’t use the knowledge base themself, they will certainly not recommend it to others.