I’ve written C++ for the last 15 years, but before I got my degree I was a reporter and editor on a daily newspaper. Those jobs demand technical writer skills, minus the tech: Reporters turn conversations into text. Editors organize and clarify. Daily project reviews are performed by thousands of readers.
Then as an engineer I put the tech back in. Though “technical writer” wasn’t my title, I’ve done years of on-the-job technical writing and editing. I enjoy the work and I’m eager to help this community.
That C++ programming I did was for hardware verification. Once a chip is made bugs are unfixable. We simulated hardware designs extensively.
Our hardware designers were doing no unit test — the verif tool took weeks to learn and needed too much setup. We were seeing bugs everyone wished had been caught earlier.
I created a unit sim environment for hardware designers and promoted it using this 6,700-word document.
Since nobody approached me I thought I’d failed, but it turned out to have been a documentation success story — hardware designers read the spec and started using the environment on their own.
My management was knocking around a vision document, the way management does. I thought the first paragraph could be made more exciting. Here it is, before and after my changes.
In the coming decade, workloads running on large-scale HPC and commercial systems will increasingly be characterized by complex, multi-faceted workflows. These workflows will digest and analyze enormous amounts of data of varying types, from varying sources and with varying degrees of persistence. These workflows will have huge computational demands and the need for cognitive feedback and steering from advanced AI technology. Hence, there is an opportunity for a converged, cognitive system architecture that can address the needs of both computational worlds. Systems based on this architecture will have to be flexible in nature, highly secure, reasonably straight forward to program, and highly data capable as well as beingcomputationally powerful, cost effective, and energy efficient. This document spells out a vision for just such an architecture: [Redacted] Architecture.
Complex, multifaceted workflows will dominate large-scale HPC and commercial systems in the coming decade. Enormous quantities of data — varied in sources, types, and persistence — will in turn demand extraordinary computational power for analysis. A new kind of machine is needed to meet both the data and computational dimensions of these workloads. We believe we know how to build such a machine — a [Redacted] Architecture — and how also to make it flexible, secure, cost-effective, energy-efficient, and realistically programmable.
I proposed this opening-page text for The Better Docs Project.
In IBM’s Research Division, where I worked, documentation was a frequent casualty. I struck a deal with a designer whose work I had to verify: If he explained it, I’d write the spec. This is a section from that spec, for which I ended up writing 8,000 words. The hardware was doing things that had never been done in a commercial machine and the concepts were new to everyone. An engineer high in IBM later told the designer the spec was one of the best he’d seen.