Technical Writer

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.

Last Modified : January 1st, 2007
Filed under : Knowledge Base
Navigate : Previous post / Next post