John E. Darrow
Details of Experience
See also resumé
My "Cover Letter"
I love English, love one-on-one and classroom teaching, love helping others understand whatever topic I can help with, whether via story telling or points distilled to slides. I enjoy putting left and right brain halves together, where the collision of logic and organization and art serves the student or whatever consumer of my effort.
As you read the details of my corporate writing, my programming, and my hobby interests, below, certain themes jump out over and over: my passion for process improvement, my eye for a better experience for the audience, my seeking ways to arrive at a consensus efficiently. I have a big heart for tech writers; in my coding--whether on their team or not--I've strongly advocated for helping them, for I understand their needs.
Thanks for reading! ~John
Corporate Writing and Programming
Course developer; Software engineer
This role began when an upper-level manager moved me from my staff tech writing role (where he observed I was programming for the needs of tech writers) to a new software engineering group he was forming. When I reminded him I lacked the formal training of career software engineers, he assured me I would be trained into the software engineering role he had in mind.
Early in this new position, I was declared to be a course developer. I had given verbose feedback for improvements of a course that I and project mates attended. My background in teaching was part of the upper manager's decision to appoint me as the lead for developing and presenting this course with the architects. I created and conducted surveys by which we assessed each presentation, influencing overhauls of the course for the next pass. I produced two hours of videos by which eBay employees around the world could learn the same material as in the full-day in-class offering.
My initial team was asked to develop software that assessed internal coding against a set of internal standards documents. As a past tech writer, I was the natural choice for the task of distilling verbose standards sentences into concise, consistent assertion statements. Teammates would then code to report pass/fail for code submitted by internal teams against those assertions. (This project was then moved to another team.)
In my last team as software engineer (the engineering team supporting eBay's "Developer Portal"), I helped code and test the Node.js web development (both back end and front end) of the replacement of the API Reference generator I had developed in Java in prior years as a tech writer. The new offering was demonstrated at the "eBay Connect" developers conference mid 6/2017. (I had received 3-4 months' training in Node.js.)
I devised and delivered a utility which significantly shortened the tech writer task of reconciling two schemas, a task that could easily take one writer a half a day. I envisioned a process improvement and proposed to three managers that, in two weeks, I could deliver a utility which would help shorten this task for writers. With their go-ahead (granted though I emphasized this would be throw-away code, as we all knew that Engineering would someday overhaul a particular system and eliminate this issue), I delivered (though a couple of days over estimate). The tech writers were ecstatic that the utility reduced their effort by several hours. (My hack also served as a sort of working model, illuminating for the Engineers some key things they would need to address in their eventual formal solution.)
In a brief stint on an API development team, I contributed in minor ways to the development of and integration and unit testing of the Order API (REST). It was then that I learned the basic concepts of REST services, Spring annotations, mockito. Regarding git/GitHub, I learned branching, a healthy PRs system, and the significant difference between rebase and merge.
I was selected as an evaluator of Industrial Logic's online modules for Java programming, to advise whether such should be rolled out as training for all eBay developers. Personal benefit was high: what I learned has transformed my coding practices--the stuff of test-driven development, refactoring techniques; composition, extracting, inlining... what a profound change in my understand and approach in coding.
I very much enjoy programming, and programming will continue to have its place in my career. But my sweet spot is technical writing, and that is what I am returning to. I am very grateful to have picked up new skills in programming in Node.js and Java.
Staff technical writer and technologist -- the story of conversion of schema to HTML
By far my greatest achievement at eBay was that I was the guy who created the original "schema to HTML pages" API Reference generator for eBay, developing and maintaining it from 2006 to 2017 all by myself. I did this in my tech writing role, leveraging my hobbyist Java skills. While I had not received formal training in software concepts and styles, I nonetheless gained a reputation for rapidly delivering solutions by whatever means.
The design of the API Reference itself with all its bells and whistles--this was the work of three of us. We would brainstorm about what else we might add, and then I'd figure out how to do it in Java, etc. We were definitely on the right track: external developers routinely praised eBay's API Reference documentation as the best they had encountered.
Parts of this reference that I would say best illustrate the complexity I addressed would be (a) the Field Index and (b) any call page's "payload model" or the table of field definitions appearing below the payload view.
The Field Index organizes the schema by field name. The same field name can appear in different types. A field might appear at the top of the payload or be deeply nested. A field might be part of a request payload or part of what is returned. My Field Index page result provided links to every use of a particular field, identifying by which call and by request or response of that call.
The payload model or view is what has set apart eBay's API Reference documentation from the competition. eBay's API Reference for an API presents not only a traditional "type view" like this (a type with its list of fields or properties), but also a full descendancy view of the request payload and the response for a call. In general, customers loved this "schema view at a glance". They came to rely on the enhanced views that we produced, confirming our product ideas were on the right track.
I was tech writing for eBay, and I started learning about the lengthy, command-driven doc build process run by a coworker. With batch scripts and GUI automation software, I turned a two day process, where the build person was busy monitoring it or typing commands for it, into a three hour process which auto-emailed the doc build person whenever a big portion of the task was done and the next step needed to be started. This freed the build person to do actual tech writing while the build was going, as it requires far less of their attention.
Savi hired me to advise their documentation team for an upcoming API documentation project. I helped identify the skills needed by the documentation team as a whole. I proposed that I could teach all of them how to document a Java API, plus some core concepts of Java programming (to increase their ability with code samples) and could teach them how to write for javadoc. They hired me for that training activity.
I wrote a program that would convert javadoc comments into documentation matching a particular company's FrameMaker template style. I demonstrated to the VP of the company that I could convert their code base into 1200 pages of skeleton documentation in just a few minutes; I computed that a skilled writer, taking 10 to 15 minutes to manually set up a page, would take 2 to 3 weeks, with their effort going mostly into formatting. Writers should be concerned primarily with content; writers should be spared of formatting--leave that to automation.
I self-appointed to lead a corporate committee (with representatives from multiple IBM sites) in establishing benchmark tests to be used on several computer-aided-design platforms we were evaluating. We were alloted two weeks to deliver our proposal for benchmark tests; we delivered in one week.
The internet was pretty new stuff in 1994. At that time, I wrote a program to convert GML-format documentation into HTML. Around that time, IBM wanted to address the issue of there being three different IBM sites wrote their own documentation on the same topic. I was asked to evaluate the three "competing" documents to assess how we might choose one. I proposed that I could create one new documentation set that represented the best of the three and was awarded the task. I overhauled the documentation to have a consistent style. And finally I used my GML-to- HTML converter to convert all of this GML-sourced documentation into an HTML web equivalent. It was quite the cool thing in 1994. I completed the project on schedule, a schedule which several (ok, the competition) had slammed as too aggressive.
My department offered a two week class. I proposed that I could overhaul the 100 page tutorial (written by five authors in varying styles) with the goal of shortening the class (the time we took students away from their normal jobs). The end result was a tutorial that worked for a 1 week course and which eliminated an unnecessary dependency on another course. In teaching the course, I observed a significant reduction in student questions and higher retention.
README: my commentary on the writing samples
Photo uploader for my wife's business
I observed the pain for my wife in uploading photos to a web site, having to click this and type that and select calendar dates--repeating for all of the hundreds of photos she might need to get into the system. This could easily take an hour, requiring her constant involvement and error checking.
I wrote one program (Perl) to generate a flat file "database" from her local inventory of photos and facts, and wrote another program (Java Selenium Chrome driver) to do all the UI interaction for uploading based on that flat file. Result: She starts the latter program and walks away. The program shows a progress bar and continually updates estimated completion time based on current internet speed. Eliminating all the human pauses and mouse moves, it has cut the upload time itself down to 15-30 minutes. Over and over, my wife has expressed how much this has freed her.
For my use only: a multi-threaded desktop GUI. With it I can manipulate details associated with a photo (people's names, location, story) and can pick from a combo-box list of categories to assign all categories that apply to the photo. The HTML generator then takes these flat file facts and regenerates every category page to account for the altered photo facts. And it does this in each of several languages (English, Spanish, German, Swedish, Norwegian, Italian and Japanese), as I localized key phrases appearing on the page and enlisted fans from around the world to provide the translations. Oh my gosh, yes, dynamic HTML from a DB would be wonderful. Someday. In the meantime, we see this old school look derived from an old school Java approach!
(For a hint at my flat file approach, see my javadoc--where the count of "800" pages is so out of date, as there are now tens of thousands of pages: http://www.phoons.com/john/phoonsdoc/phoons.html )
Available to viewers of phoons.com:
Online two-person (same browser) card game, with AI
Stock picker web page generator
Created multi-threaded stock price trend software that downloaded and parsed historical financial data from the internet for thousands of stocks, identifying "the best" per my specified criteria and created a web page of links to corresponding thumbnails of Yahoo stock charts.
Graphical demonstration of understanding of multi-threading
Created a Java applet which randomized number of dishes held my multiple "washer" roles. Each washer would rinse a dish and put it in the single drip rack--if there was room in the rack. Multiple "dryer" roles would grab a dish from the drip rack when ready for their next dish. This proved my understanding of wait() and notifyAll()--and of some simple Java double-buffering graphics/painting/updating.
Initially, I created this to convert GPS coordinates to a map I could print out--so
I could search for geocaches without a GPS device. Then I updated it so that a person can pick a spot on the
map, get coordinates and enter those coordinates in another page of mine where I can associate
a phoon photo with its location on Earth. Try the country links in the green box.
(Last maintained in early 2000s?)