An Overview of Document Types….

I thought it would be helpful to write about the different document types I have encountered while working as a technical writer in various industries (environmental, telecommunications, medical software, medical communications, etc.).

I have made an attempt to define the documents based on my own ideas about them. The text in red was added in after googling the search term define: [document type].

White Paper: almost like a marketing piece / proposal type of document. Its purpose is to outline in great detail new technologies or existing technologies in order to present the information to some third party who usually has a stake in funding for that project. “Used to educate readers and help people make decisions.” “A purpose to educate industry customers.”

End-User Manual: aimed towards end-users of a software program or other piece of technology. The audience can vary in technical aptitude from absolute beginner to advanced.

Release Notes: outlines all new features of an updated version of software. Usually with a table of contents and brief paraphrase of all new features. From Wikipedia: “A release note is usually a terse summary or recent changes, enhancements and bug fixes in a particular software release.” “Not a substitute for user guides.”

FAQs: Frequently Asked Questions. A compilation of questions about a piece of software or a system in a question & answer format. Best if based on real life questions asked by customers / clients.

Data Sheet: OK, this one I haven’t actually ever had to do before……but it seems to keep popping up. So from Wikipedia: “A document summarizing the performance and other characteristics of a component (i.e. an electronic component), a sub system (i.e. a power supply) or software in sufficient detail to be used by a design engineer to design the component into a system.”

Online Video: These, I absolutely just love! A short segment, usually running from 3 to 6 minutes in length with a purpose to demonstrate / visually show how something works. This could be how to use a component of the software, how to carry out some kind of procedure or function, or really anything under the sun where the user could get a better idea by watching rather than reading about it.

Find me on Twitter: @jacbird and @masitblog

How to work well with others (as a technical writer)….

In my three years of working as a technical writer, surprisingly, I have learned a few things about working well with others. I didn’t think that would be such a huge part of the job, but it has proven itself to be time and time again. So, I present you with a few tips and tricks that I have learned.

  • Listen well and good to what the other person is saying
  • Try to not make assumptions about what they are saying
  • Don’t judge people based on what you think you might know about them. Basically, try to treat everyone the same way.
  • Try to offer prompt, good quality and cheerful service that people can rely on
  • You will find yourself working with people from all walks of life and cultures. It’s sometimes hard not to make judgments, but it’s the worst thing you can do
  • Chill out and don’t be a stress case when working with people. It’s not rocket science (unless of course, it is)
  • Be patient with people and respect their time; plan around them if you have to
  • I heard this on the radio once, but I’ll repeat it here: you can’t go wrong with tact, diplomacy and respect

A Day in the Life of a Chocoholic….

OK, so lets step back from technical writing for a moment, and talk about chocolate.


I am a self confessed chocoholic. I know I’m not alone in this, and for those of you who don’t understand, I thought I would offer a glimpse into the mind of one.


A long time ago, it didn’t matter what type of chocolate I ate – I really didn’t know any better. Until one day, a friend suggested that in order to control my cravings, I only should eat the “good quality chocolate”. You know, like the kind you can only get from those little chocolate shops in the mall.


After a while, you can really start to tell the difference! To me, chocolate of poor quality tastes the same as eating a sugar cube with perhaps a layer of some synthetic brown material over top of it. Good quality chocolate isn’t quite as sweet, and the consistency is different. It’s smoother and melts in your mouth better.

The suggestion really did work wonders for me. In fact, I’d even say I’m a bit of a chocolate snob these days. And because of the price of all that good quality chocolate, I don’t end up eating bags and bags of it. Well except for that one time, when I ate an entire bag of chocolate covered almonds in one sitting, and got really sick, but I won’t talk about that here.

Find me on Twitter: jacbird

Various Uses of XML

It’s 11:00 pm, on a Friday night…….so why not write an article about the various uses of XML? You’ve probably heard that term before, and I’m sure you will hear it again. In my mind, it’s a way to make the information displayed on the internet more concise, searchable, and organized.

I first became interested in XML when I found out that it’s something technical writers should know, and that it had something to do with RSS feeds.

RSS Feeds:

RSS aggregator programs read RSS feeds on news sites and blog sites to allow you, the reader, to become aware of new and recent information without having to do it yourself. The RSS aggregator reads the RSS feed which is written in XML. The funny thing, is that the RSS aggregator program reads the feed in XML, but you could too, since XML is human-readable! Of course though, you’re not a robot, and so I’m sure you don’t want to be the one to scan all those feeds and see which ones are new, and then display them to the internet.


Anything about math is cool, right? Well, now they’ve figured out how to use XML to describe math formulas and bring them to the World Wide Web. And you thought you were done with math after first year calculus.

I’m pleased to tell you that the XML not only describes how math formulas should be displayed (presentation) but even what the different formula components mean (content). Read more about it at


You can use XML to define the type of information contained in a document, and thus make that information easier to search. That is because unlike HTML, XML describes the information rather than just presents it. So for instance, you could use XML to denote that Chrysanthemum is a book title rather than a plant by using a book title tag <book_title>Chrysanthemum</book_title>.

Now a web robot would know that in this instance, Chrysanthemum is a book title and not a flower.

Other Uses:

Now what I will do, is list a few other uses of XML and send you off to learn more about them on your own. I know I’ve made XML sound so exciting, so you won’t be able to wait any longer will you?

DITA (Darwin Information Typing Architecture); SVG (Scalable Vector Graphics); Databases; AJAX (Asynchronous Javascript and XML).

Find me on Twitter: jacbird