Technical Writer

In his article The Good, The Bad and the Ugly of SharePoint 2007 Development over at SharePoint Buzz.com, the author talks about the ‘ugly’ of SharePoint 2007 as being

1. Selling - I have had the hardest time selling Sharepoint to my company. The functionality it provides out of the box alone would save the company in support calls, millions of dollars in mismanaged folders and bring in some organization into the company…

2. Training … Sharepoint is something I strongly believe the company can benefit from. However … the company is not willing to fork out the thousands of dollars for the product let alone the hundreds of dollars and time that I would need to train myself properly for the Sharepoint environment …

The Good, The Bad and the Ugly of SharePoint 2007 Development, by SharePoint Buzz.com, posted 5 January 2007.

(The original article was based on a post called The good and bad of MOSS 2007 development, New Year, New Job, New Projects!, by Sezai Komur.)

SharePoint Buzz sounds as though his company has not implemented SharePoint yet, and he cannot convince them to do it, but let me tell you, for some companies it’s almost as bad even once SharePoint is implemented.

Let’s use my company as an example. Two years ago the then head of IT decided to buy SharePoint.  There was no consultation with the end users, it was just a done deal. Some money was made available for portal design, and one of the IT support staff was sent on a two-day course—but only because we insisted—to learn how to set it up, integrate active directory, and so on.

So the in-house designer and myself, as content manager, taught ourselves as we implemented it. There was no budget for training. 

There is still no budget for training.  Even now I still answer most of the enquiries about access and security because there is no budget to send the support team on training courses, and “They can’t afford the time out for internal training”.

As for end users—whenever I try to organise internal training for end users I get, “They don’t need to know”, or “The program isn’t important enough in their day-to-day work for us to take them away from their jobs”, and so on.

Most people go out of their way to resist change.  It’s human nature.  I don’t blame them for finding excuses not to use SharePoint.  They need to be sold on the product.

Selling SharePoint is the hard part.

I can sit down with individual users in the company, show them what a great product SharePoint is, and what you can do with it. They are often enthusiastic, but if we can’t implement something immediately that enthusiasm wanes.  Of course it does. Out of sight, out of mind.

Until I can sell it to the people who matter—the heads of department—the people who can issue a directive and say, “You will do it this way from now on”, SharePoint is never going to provide the benefits it should.

It’s a hard sell. These department managers were mostly here two years ago. They had SharePoint presented to them as a fait accompli. They didn’t want it. They didn’t see any need for it.

We, the people who implemented it, didn’t know enough about it in those first vital months to sell it to the people who mattered.

We’re slowly getting people onto SharePoint, but it’s a hard slog. Much harder than it should be. 

Obviously, with the experience we have now, we would do a better job of selling the product in those important few months, and we would have concentrated on the people who really needed to be sold to.  But without that training, without that experience, we did it the hard way, and we have a lot of ground to catch up.

So SharePoint Buzz, I say you have captured the two ‘ugly’ points about SharePoint really well. It’s a great product, and I mean SharePoint 2003 as well as 2007.

It is a hard sell, and it’s even harder to sell (not to mention implement), without training.

Today I had one of those ‘Eureka!’ moments where a whole lot of disconnected information suddenly fell into place. Good feeling.

As a self-taught SharePoint user, there are big gaps in my knowledge, and the worst thing is that much of the time I don’t know what I don’t know. 

I also dabble a bit more in the technical details than the average SharePoint end user, but I’m not a developer. I haven’t coded (as a job) in a very long time, so while I can understand the concepts I definitely couldn’t sit down and write web parts using .NET without a lot of upskilling.

I am moderately comfortable with Javascript, however.

I dip in and out of the Microsoft SharePoint sites. Each time I understand a little more. Today I decided to take another look at the Hello World Custom Menu Web Part.

This rather nifty little example shows you how to add a menu item to the Edit menu for documents in a document library.  The example they start with displays a “Hello World” dialog box, but then they go on to show how to use the same process to add a “send an email link”, which emails a link to the document you are currently looking at.

Cool.

So, how do they do it?

They add a content editor web part, put some Javascript into it, and then hide it. The Javascript adds the menu option to the document library, which is another web part on the same page.

That’s when I had the Eureka moment.

A content editor web part isn’t just for adding text. 

I have only ever used content editor web parts to add text up to now. Admittedly, I have embedded Javascript in that text sometimes, but the Javascript has always been specific to that particular web part. Simple little things like a date countdown displayed on the page, or mouseover functionality.

Now I suddenly realised that the Javascript I add to that content editor web part can be used to affect other parts of the page. And I remembered, then, an experiment I tried with inline styles early on in my SharePoint life. An experiment I stopped abruptly because the styles in that particular web part impacted the rest of the page. I didn’t understand why at the time, and didn’t follow it through. Now I understand. It’s not just Javascript that I can use. It’s any content (within reason) that can be added to a web page.

It’s so simple. So obvious. Now it’s starting to make sense.

I was reading old posts on one of the tech writer forums and one of the members asked how to get a job as a technical writer. They were reluctant to go through one of the recruitment agencies.

I found that attitude interesting, because here in Australia recruitment agencies are the main source of jobs for technical writers.  I won’t go so far as to say the only source, but short of having an extensive network of friends who will recommend you, if you refuse to touch the agencies then your job prospects are severely limited.  Likewise your pay.

Which agencies should you go through?

Pick the agencies that deal with IT. You may believe that you are not an IT person but that’s irrelevant. Tech writing jobs generally go through IT.  Seek is probably the largest in Australia. 

Otherwise, choose a boutique agency that deals specifically with technical writers, such as Tech Writer.

Each agency web site will give you hints and tips about what you can do to prepare your resume, and in Tech Writer’s case, they even mention the portfolio briefly.  (More about portfolios in another blog.)

Most agencies accept resumes even when they don’t have work. They keep them on file and will contact you if a job becomes available. It pays to keep these resumes up-to-date. Keep a list of who you have sent your resume to, along with your work availability. For example, if you are contracted for the next six months, say so.

Some agencies also send you an automatic email when jobs that suit your criteria become available. For example, I get all the job alerts for tech writers for jobs in my state from Seek.

Just don’t ignore the agencies altogether. Here in Australia, at least, you are cutting yourself off from the major source of work.

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.