Search results

The Tell-Tale Project — Guest Post by Edgar Allan Poe, Technical Writer

by Edgar Allen Poe on Oct 31, 2018
categories: technical-writing

The following is a guest post by Edgar Allen Poe. Poe completed many works of both fiction and nonfiction in his life, including 'The Raven', 'The Fall of the House of Usher', 'Eureka', and most famously, the 'Tell-Tale Heart'. Many are unaware that one of Poe's first jobs was as a technical writer. In this post, he explains some deep conflicts and challenges he had on one project, and how he overcame the challenges.

The Tell-Tale Project

You may think me to be crazy when you hear this story. But I am not crazy. I’m as level-headed and logical as I’ve ever been. Just listen to my story. I will relate all the details in the most excruciating plainness such that no other interpretation can be reached.

I was asked to document, as a routine assignment, a new software application that was part of a redesign effort one the top programmers had been exclusively working on. He called the project Moby Dick, which I thought strange, but who can tell what stories are behind the names, the seemingly nonsensical names that programmers develop for their pet projects.

I worked in my cube. Tirelessly, day after day. I meticulously created instructions. I know my job and execute it with exactness. This exactness is precisely what led to the conditions I alluded to at the beginning of this story, but let me not get ahead of myself.

As I was documenting Moby Dick, describing how every figurative software cog and bolt worked, it began to possess my attention in ways I had not anticipated. The work began to remain in the primal focus of my mind with more force than any other software project had ever occupied my attention. I will even admit that many times, late at night, I remained awake contemplating the perplexities of the project, much beyond a reasonable time.

I do have other priorities, and errands. But despite my best efforts to redirect my attention, my thoughts always came back to Moby Dick. It was always one step out of sync, it seemed, for no valid reason. I started work on the project two months ago, preparing the documentation for the mid-month release that culminates our 8 week epic cycles. The engineer said to begin documenting early in the process, which I readily agreed to, even though his sense of timing seemed a bit odd to me.

I sized up the screens and began making detailed notes of every task and feature in the application, turning the rigor of my mind to subdue the application’s complexity into simple prose. Simple prose, mind you. My mantra and the mantra of anyone who knows this craft.

All seemed to go well, but after the third week, I began to notice some inconsistencies with the application. Screens I had already documented began to show error. I reviewed the topics I’d already written, and I noticed some steps were out of order, some button names had changed.

I made the updates immediately. I was expected, as a contributing team member, to deliver the exact documentation upon the release of the feature. Any inconsistencies would impact with negative attention on the performance reviews of my work. And I am the most detailed, conscientious writer you will ever meet. Yes, if we do meet some day.

If the random inconsistencies were the whole of it, I would not have started you down the path of this story. I would not have wasted your time. Have patience as I relate the detail, because you must understand the detail to grasp the complexity of the scenario.

After the fourth week, I revisited some of the documentation I’d written, a dozen topics on the configuration and creation of the system architecture, when I realized yet again more changes. The topics I’d already updated had even more error. The programmer had changed once more the workflow and button names. The dialog box titles had new words. The screenshots that I’d taken and meticulously cropped, bordered, and altered with fictitious data had to be redone.

The first and second instance of this mid-project alteration may have been coincidence. It may have been the variations of a project whose life cycle changed with the changing times. But what would be the chances of the same screens changing yet again on the fifth and sixth weeks?

Even two thirds of the way through the project, the same screen had undergone slight changes in button names, drop-down menu lists. Where a hyphen was previously present, it was now absent. A title case capitalization had been altered to a sentence case. A comma omitted in a series before the last item was now inserted.

Was I going mad? Was the style changing? There were no textual guides for the project. They would have come from me, but I had not dictated any restriction. I began to look at the programmer responsible for this part of Moby Dick. Was he playing games with me? Could he be doing it on purpose?

I’d never had formal discourse with the programmer before, though I’d seen him many times walking the hallways, entering the kitchen, washing his hands in the lavatory. He was a silent one and kept to himself.

At first I did not see any connection between the recent changes and the screens he programmed — until I began to study his actions and character more closely. He had less than favorable sentiments toward me, I believe. Although he toiled away in silence, occasionally he would steal a glance in my direction and snicker. He would smirk and let out of a laugh, which before I would have dismissed as part of the programmer’s ongoing dialogue with the code he writes, but this programmer was playing games with my mind. He was purposefully changing the screens to invalidate my documentation.

Did he have a grudge against technical writers? Had I offended the programmer in some way? I scanned my mind for some ill-flavored interaction, some bitter words spoken, but I recalled none. No doubt he knew my name, though barely did I know his.

At the sixth week, as the first release candidate was prepared, he yet again changed the screens. Instead of radio buttons, check boxes. Instead of regular dialog boxes, modals with dimmed backgrounds. Instead of 3px rounded corners, 6px rounded corners. A slight shade of beige #e8e7d1 changed to #e2e1cf. Changes from single to double quotation marks in all the places where I’d previously had double quotation marks.

I said I am meticulous. I did not want to slip up in any way that would jeopardize my job and reputation in the industry. A technical writer’s words are only as good as they are accurate and clear.

I begin to consider ways to protect myself. If the programmer had schemes for my demise, I had to counter them, and efficiently so. I had to anticipate his move and respond softly and sharply, cutting him off before he can follow through with his plans.

Perhaps he had a friend or family member he wanted to move into my position. Perhaps he had too much spare time on his hands. Perhaps he found pleasure in the sadistic torment of the lonely employees around him.

As is the case with most programmers, I gathered that his chief desire, though he wouldn’t admit it, was to propound his own knowledge and establish himself as the alpha tech. He wanted set a trap to have me excised from the team, if only to prove that he could, like some code puzzle one solves for the mere joy of solving it, not for its utility or need.

As soon as I saw through his schemes, to get rid of me by evoking incompetence, I deliberated with extreme caution about the various ways I might counter his undermining. I contemplated placing a large magnet next to his computer, or balancing a tall glass of water on the post beside his keyboard, or installing malicious code through a trojan. But though these attempts might destroy the tool, he would no doubt replace it with another. He no doubt had several computers already. Like chopping off the head of a Greek Hydra monster, two would grow back in place.

The seventh week of the release and yet again, all my changes previously now required random reversions back to earlier states. From title case to sentence case and now in places, smallcaps. From hex #e2e1cf to #edecd9. From Arial font to Helvetica. Eighteen pixels of line height instead of 24 pixels. An additional (and I might add, unnecessary) word in the description below the page title. An em dash instead of an en dash. Curly quotation marks instead of straight quotation marks. And the final blow, an unnecessary exclamation mark at the end of a phrase. All my screenshots had to be redone. My instructions about error messages and labels, now invalid, required reconstruction.

While before I may have only been suspicious, now I knew he had a plan. Whatever nefarious motives percolated under his skin, he was no doubt the ferry driver of hell, looking to load me up and cart me away from my place, to destroy my reputation for clarity and plainness.

With one week left before release, I had to act quickly, but what? What logic to employ that would stun one who swims in the complexities of code? I stayed awake late at night ruminating on the matter. I looked to different models of extortion and revenge to surprise my assailant with a curve ball of sorts, one he might see and attempt to dodge at the last minute but be unavoidably hit by it.

On my sixth cup of tea at three in the morning, I came upon the exact idea. In my documentation, I laid the seeds of destruction. A hidden pattern, one so subtle that only a genius could detect it. I laid it word by word, revealing meaning diagonally and backwards, from one page to the next. You must be oh so careful and clever to see it, but I infused it page after page. Like a word search, but woven into the very fabric and number sequences of the documentation. Penetrable only with a cipher, but once penetrated, plain as day.

Hidden messages, patterns below the surface, have existed from ancient times to present. They are a means of transmitting deeper meaning in plain sight. The Book of Revelation, penned by John at a time of political exile in Roman occupation, contained rich symbols and patterns meant to articulate a harsh critique of oppression. The Bavarian Illuminati, seeking to upend corruption and political machinations, masterminded the French Revolution through a coordinated web of hidden communication. The Freemasons, the Knights of Pythias, the Sons of America — these groups, the incubators of our democracy, found a way to encode their rhetoric in the lettered strands of our language.

And so I toiled. I reworked the content, double-laid the sentences, implemented chaismus, inverted pyramid constructions, placed image on top of image, and worked relentless night after night, consuming weekends and spare time, until my frivolous social interactions had all become extinct, a distant memory. Just a lone candle burning at night in a quiet, dark room while I typed at a keyboard.

I should force you to detect it yourself, to test your wits. But I am not that cruel. I merely exposed the insidious programmer for the anti-alpha he was. If given the cipher, you will find I inserted — sometimes spelled backwards, or cornered in on both sides by misdirecting words, or diagonal across the page, or written with special algorithms (Nth +1 letter), or resized as 1pt font in graphics — the simple but true message on every page of the documentation.

In other places, I added the special meaning in parenthetical statements which, if read in sequence apart from the text, spelled the phrase. And I laughed devilishly while noting how this phrase actually described the true nature of our interactions, aligning within my documentation domain. Yes, in principle, I was only documenting the characteristics of the interface — working in truth and exactness.

I weaved the invisible code because I wanted him to know that I knew his plan from the start. I had outcoded the coder. All of this hidden meaning was perfectly sewn in the documentation, but so seamlessly that it was impossible to see it without the insight that one with an eye for meticulous detail possesses.

When the day might arrive when he might confront me, to give me a dirty exchange in the kitchen about my employment or character, perhaps insulting my intelligence and capacity to document his code, I would be equipped with the right response. I would tell him, casually, that I had slandered his nature in the very document that described — in perfect harmony — the code he had written. I would tell him that he was, in fact, mad, just as the documentation outlined so clearly for everyone to see.

When would we meet? Perhaps in an encounter at the end of the workday, riding down the elevator together, as he might look in my direction and snicker, I would drop a hint of the cipher, the text within a text, and he would be at a loss. Or maybe in the breakroom, as he washes up a cup and looks at me in the mirror and chuckles, like he knows an inside joke I don’t, I would casually remark about the hidden text. It would drive him mad. It would unhinge him permanently.

At the eighth week, three days before release, he countered yet again, forcing me to rework the pattern under my instructions to align once more with the intricate interface he had constructed, one so obviously targeted at my destruction and discrediting that any fool could see.

But I kept silent, pretending all is well, not even sweating, because I knew I could get the upper hand. His efforts did not deter me. I stayed up day and night altering the pattern to fit the new interface design of his rhetoric. I worked meticulously to restore what he tried to take from me. And on the day of release, I published the documentation for all the world to see.

Even upon release, the programmer did not immediately see the pattern, nor did anyone else. Our chance encounter still lurked in the future at some distant meeting he no doubt naively entertained.

A few weeks later, our engineering lead called the project team together for a post-mortem discussion to discuss the pros and cons of the project. The lead sat at the head of a large table and made smalltalk about the weekend. He talked about the weather, and conferences.

Did he know? The programmer for Moby Dick joined in the smalltalk with casual banter. Still talking about movies and parks and other nonsense. No one mentioned the documentation, but I knew the programmer was aware. From subtle side glances I knew he knew. He had seen the pattern. He had started to catch glimpses in the corners, which was driving him mad. It was only a matter of time before it came fully into view.

It occurred to me that he might decide to expose me during the post-mortem meeting. Rather than a personal confrontation, a secret kept between the both of us, he might bring my actions public here and now.

My heart was thumping. Was he going to circle around and reveal, in this very meeting, the pattern I had sewn into the documentation? The Moby Dick programmer looked once again in my direction, looking for some cue from me to evaluate his move. He was waiting for the right minute. He had what appeared to be printouts in his hand. His plan was to reveal it the meeting, to call me out in front of everyone rather than meeting me discreetly. If he stated that he knew before I could allude to it, his knowing would subvert my claims at his idiocy.

My heart raced. I started to sweat. My knees were shaking with nervous jostling. I had a pen in my hand to take notes, but I now scribbled randomly on the page, trying to make sense of some random pattern, attempting to force a way out by drawing a door on the page.

He knew, and would no doubt sneak in a patch, or some further change, destroying my work. I squeezed my fists as hard as I could several times, releasing, and then squeezing, and releasing. A technique for relaxation — but it only heightened my breathing and anxiety. My breaths shortened. Others looked at me now.

The programmer stared directly at me, and as he opened his mouth to condemn me, I had to get the upper hand. I had to change the plan to counter his changing plan. Anticipate the move. Read from the windows of his soul his internal designs. It wouldn’t be a private meeting. It wouldn’t be a personal encounter. It was going to be right here and now. I had to let everyone know before he announced that he knew. His knowing would trump me.

The timing was right. I stood up and presented the papers in my hand. I pointed out the secret text I had circled in red. All eyes focused on the red in the documentation. A few let out gasps. The programmer stared in shock. I had anticipated his move and blocked him at the last minute. He had no choice but to fold. The red circles, after I carefully aligned them with the cipher, spelled the programmer’s name, his geo-coordinates, and a future date three years hence. The unknown at that date would haunt him, would make him fear what was coming. What would occur at the future date? At those coordinates? Retaliation? An apocalyptic doomsday? A termination of sorts? The ambiguity unmoored him, I could see it. Plain as day. It would incite his submission to conform to my documentation, as I had written it. A reversal of hierarchy through fear. His fingers trembling on the keyboard for years to come.

The post-mortem meeting continued, but I was escorted from it. Moby Dick was my last project at the company, and I have been looking for work ever since. But in the quiet moments when I am at home alone, far away from Moby Dick, I can sometimes hear the programmer laughing, and then his laugh changes to a faint sob. I beat him. I beat him.


This post was originally published on 10-26-2013. It was updated for this republication.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.