Writing A Technical Article, Pt. 1: Background

I thought I’d try blogging the development of a technical article; it might prove interesting to, I dunno’, 3 people in the world.

I’ve been contracted to write a 2,500-words-plus-listings article on using AMD’s CodeAnalyst profiler with Eclipse, especially relating to multithreaded / multicore development. So that’s a pretty beefy article, about twice the length of a typical technical article in a print magazine. CodeAnalyst works with native code, so my sample program(s) pretty much have to be written in C++ — anything else would limit the audience.

AMD targets an experienced audience, so the educational goals for the article are “The reader will be able to…”

  • … enable and gather data using CodeAnalyst from within Eclipse CDT
  • … navigate within the main profiles provided
  • … recognize the profile most clearly associated with their performance limits
  • … determine the source-code lines associated with a performance issue
  • … after making code changes, compare the performance of subsequent runs”

Which is a heck of a lot of ground to cover. So the end result will be something like an advanced tutorial that you might get towards the end of a piece of documentation.

My professional goals are to deliver a technically sound article that satisfies my client’s goals within a profitable range of hours. I can control that primarily by manipulating my sample program(s); the amount of time I need to research the actual use of Eclipse or CodeAnalyst is minimal, since I know both products. The research aspect of the article — always the most time-consuming in a technical article — will be the development of sample program(s) that:

  • have a performance-limit that can be ameliorated,
  • are comprehensible, and
  • can be distributed (this limits my use of libraries)

My personal goals are to make sample programs that are interesting in and of themselves. This is a weakness on my part, but what can you do? In this particular case, I hope to implement some significant part of the algorithms used for content-aware image resizing. I have no intention, or interest, in recreating the GUI shown in the video. I have neither the time nor, quite honestly, the mindset — once I see the algorithm work, I can guarantee you that my interest in this will virtually disappear. That’s one reason why I’m not rich.

Next up: Part 2, Gathering Tools