Shanghai Tech Writer

I started working on a new project recently. For this project, I will be writing the entire documentation set for a new LabVIEW toolkit. This is my first 1.0 project, meaning I’ll be writing everything from scratch. It will be exciting but challenging at the same time. Last week, I wrote a documentation plan, and this week, I’ve been working with the content experts and the project manager to create an outline. Because this is a 1.0 project, I need to think about how I want to organize the entire documentation and what topics to write given the project timeline.

The documentation plan I wrote earlier gave me an overview of the project including the product I’m writing about, the purpose of the documentation, the target audience/users, the type of documentation that we want to ship with the product, the risks and challenges, and the project schedule. The hardest thing about starting a new writing project is where to even begin! Writing the documentation plan was the first step to starting a new documentation project. The next step is to create an outline or sample table of content to help organize all the topics that I need to write. That’s what I did today.

Deciphering the Specifications

I had 30+ pages of product specifications to go over. Specifications are written by the content experts to explain the product features and functions. These specifications are written in a different “language,” and my job is to translate them into plain English. I spent hours reading the specs, but I had a very difficult time understanding and organizing the content. On top of that, I couldn’t get the toolkit to work on my computer so it was hard to understand the specs. For some reason, the toolkit works perfectly fine whenever the developers come by to look at it, but the moment they leave, I get all sorts of bugs and errors.

Anyway, after several unproductive hours of staring at and deciphering the specs, I still wasn’t able to organize the content and come up with an outline. I was struck with the technical writer’s block!

Dealing with Technical Writer’s Block

So I decided to do what I do best. Stop “trying” to focus and just start somewhere. As illogical as that sounds, I think the best cure to writer’s block, whether technical writing or blogging, is to just start somewhere. Anywhere! I guess when people, like myself, try too hard to come up with the “perfect” outline or topic or post or essay or whatever, the result is usually a blank screen. That plus feelings of frustration.

Since I couldn’t come up with an outline, I decided to just start “documenting.” I created the templates for all the CHMs using FAR. Then, I created the source XML files and entered a few topics that I knew I needed to write, in no particular order. After that, I ran some internal tools to generate the HTML files from the XML files. Then, I added the generated HTML files to the project HHP. From there, I created the HHC, or table of content, and organized whatever topics I had. Then, I compiled the help and the result was a CHM with a few topics in the TOC but no actual help content. It wasn’t a complete outline but it was something. From there, I was able to identify and add a few more topics from the specs. Every time I added a few topics, I recompiled the CHM. After a few hours of repetitive coding and compiling, the result was a CHM with most of the outline done! And best of all, the templates are all in place so I can start documenting each topic right away!

Like a Jigsaw Puzzle

From this experience, I find that writing from scratch is like working on a 5000 piece jigsaw puzzle. It’s impossible to know exactly where each piece belongs. You can’t start working on a jigsaw puzzle with the mindset that you must place each piece you pick up in the right place. Just pick up a piece and if you know where it belongs, place it there. If not, pick up the next piece. And the piece after that. Look for easy-to-identify pieces like the side pieces or pieces with particular colors, shapes, or patterns. Once you start putting a few pieces here and there, it becomes easier to place the next piece.

In the same way, writing from scratch is a similar process. There might be times you know exactly what you want to write about, but most of the time, writers don’t know what to write about or where to start. In this situation, just write down whatever thoughts that come to mind. Gradually, more and more thoughts will come to mind. As you write down the bits and pieces, the writing piece will really kick off!

(No Ratings Yet)

 Loading ...

  Subscribe to RSS feed       Subscribe via e-mail