Skip navigation

Tag Archives: technical writing

I’m getting back into technical documentation at my job – in fact, I just had my work goals for the new year* approved –

  1. Rework the SharePoint documentation site (that I originally created)
  2. Collect existing documentation and write new documentation for one particular large customer
  3. Create e-learning User Guide to teach co-workers how to use the SharePoint site
  4. … (goals 4-6 are team goals that were assigned to everyone in my department)


For goal # 2, I’m looking into creating checklists that anyone in my department can use to fix problems with the particular large customer.

I’ve read Atul Gawande’s Checklist Manifesto – in fact, I got the audiobook version back when the book came out.

The major problem with Gawande’s book is that it’s long on WHY you should create and use checklists, but kind of skimpy on HOW to create them.

I’m going to review what material Gawande’s book has on creating checklists, but I’ve also started looking online for other resources, as well as adapting available materials for my particular situation here.

One of the first things I found was Project Check, which looks like it was set up about the same time that Gawande’s book came out and focuses on surgical and medical checklists. It also includes a Checklist for Checklists, a 3-column checklist designed by Gawande and Dan Boorman (the Boeing expert that Gawande worked with for the Checklist Manifesto). This checklist is available as a PDF download.

Other links:

Finally, something I think I’ll find VERY useful as I create checklists that I can store in SharePoint for my co-workers to use: (how to create a) checklist in Microsoft Excel, including conditional formatting to make the Go/No-Go result more obvious.


* yes, the new year started 3 months ago, but our goals have been finalized as of March 31.

We have an issue with process documentation where I work.

Namely, we don’t have enough. And what we do have isn’t very well organized.

For example, here’s a short Microsoft Communicator chat I had with a coworker yesterday:

Me: Good afternoon! When you have a chance, I need to talk to you about how to generate the customer list file for process D71420.
Me: I know you told me how to do it once, but I’ve forgotten.

JN: Check your sent email, you sent out an email with good directions

Me: LOL! I hope I haven’t had it it archived off…
Me: OK, found it. Thanks for the reminder.

JN: It was a good write up.

So I’ve started researching wiki software and personal wiki software. Actually, I started by searching Technical Writing on reddit, and found a post titled How can I take my company manuals to the next level?

One of the answers on that post referenced Confluence, a full-sized (not personal) commercial wiki solution from Atlassian. I’ve gone to Python Meetups at Atlassian’s office here in Austin, so I thought it was worth a look. Confluence uses Java in the backend, which isn’t a technology I’m really familiar with – but our internal web hosting group here is, so they would probably be more comfortable supporting it than some alternatives. It’s just $10 (donated to charity) for up to 10 users if you host on your own server (which would be de rigueur for our process documentation, which includes login information for customer FTP sites).

I took a first look at a couple of other full-size wiki solutions:

  • Wagn (pronounced “wagon”) runs on Ruby on Rails. It has an interesting card-based interface that reminds me a little bit of HyperCard, which might be easier for my co-workers to wrap their minds around when I’m trying to convince them to write documentation for their own jobs. It’s open-source and free – and our web hosting group is also somewhat familiar with RoR, so it might be easier for them to support than some other alternatives, such as…
  • Moin Moin is a flat-file (not database) wiki built using Python 2.x (not 3.x yet). It’s the wiki software of choice for some major open-source organizations, including Apache, Ubuntu, FreeBSD, as well as itself. It’s also available in a “personal” (not web hosted) version, which would be useful to use to demonstrate the capabilities on the way to “selling” the company on the idea of hosting our documentation in a wiki (instead of files in random locations on our network file shares).

Speaking of personal wikis, I found the following interesting:

And then I started thinking about going back to OneNote – if only there were a way to script OneNote – perhaps by accessing its XML, or maybe a PowerShell Provider that makes it easier…