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