About technical and professional writing

Who are you and what do you do?

I'm from Canada; I have lived in Vancouver since 1973, when I moved here to go to university at the University of British Columbia. After starting out in computer science, I "saw the light" and switched into math.

When I graduated, my first job was working for a very small computer consulting firm, processing sport fishing questionnaires in SPSS, implementing a high volume concert ticket printing utility in PL/1 and working on a long term project to implement a new set of forest measurement programs and reports in FORTRAN. The forestry work turned into a more long-term gig in 1980 when I became a partner in that forestry consulting company, then called Timberline.

Those were interesting days in computing, with organizations like ours transitioning from renting time on IBM mainframes to using Apple II and IBM PC microcomputers. A similar transition was happening in the minicomputer world; DEC ruled the engineering world with PDP-11s and VAXes but many new companies were offering gear with similar performance at a much lower price, based on Motorola and Intel chips and running some variant of Unix.

We acquired our first Unix system in 1984 which marked the end of our transition away from the mainframe world; and by 1986 we had outgrown that system and bought our first Sun workstations.

Throughout this time, I was responsible for making sure we had a system that worked for us, as well as most of the data analysis carried out by the company. I also found myself writing more, beginning in the late 1980s. Our clients wanted more than just endless tables of numbers and graphs; they wanted text that helped them frame and understand what the numbers were telling them. We also faced the need to write more complex proposals to get work in the first place, including both financial and technical proposals, that included everything from requirements gathering to implementation, testing and training.

As our firm grew through the 1990s and the 2000s, we all found ourselves specializing more and more. In my case, I stuck mostly with the data analysis and technical writing, mostly proposals and reports.

As the original partners and I transitioned away from ownership in the company, and as I wasn't yet ready to "retire," I found myself working more often far from home, and in particular in Chile, where we had opened our first "international" office in 2004. My data analysis and writing skills were pretty portable to Chile, though I needed (and still need) a sympathetic native Spanish speaking editor to pick the weird anglicisms off my Spanish text.

These days, I do most of my data work in Groovy, less in Java, still less in Python; my database of choice is PostgreSQL. Because a lot of our data is geographical, I use QGIS quite a bit, as well as PostGIS, the geographic extension to PostgreSQL. Since 2014, I have built quite a few data-driven web sites using Grails.

I also do most, though not all, of my work in Chile, either remotely or via a sequence of two or three week visits.

You've written a lot about open source software. What's your history there?

I started writing a column in Opensource.com in mid-2015, exploring open source music players and related topics, including where to buy music without DRM, download vendors that didn't require Windows-only download software, open formats like FLAC and Ogg, and a bit on music performances in the public domain or exiting copyright. I wrote those articles as much for me as for everyone else that read them, since I could see no value whatsoever in proprietary formats and platforms that were only sold to users of proprietary operating systems.

For me, writing for Opensource.com has been an extremely fulfilling experience; first, because it is a great way to "give back to open source", and second because being a part of the Opensource.com community has been rich and rewarding on its own.

I have picked up a lot along the way that has improved all my technical writing. I would say the most valuable lesson I have learned is the discipline of only explaining something if I'm sure my explanation is correct and tested. I'm sure we've all run across the "helpful posts" by someone saying "yeah you can solve problem X by doing A, B and C"—and then we try it, and find that actually there are parts D and E that are needed as well, and the B part doesn't actually look like what the original "helpful post" described.

I eventually moved on from the open source music players theme to writing small articles on "how to do X" in Groovy and Java, which is where I mostly remain at this time.

What is your process for writing a technical article?

The big challenge for me is picking a concise topic that fits in an article-sized explanation—or perhaps two or three articles. A good example of this is an article I wrote in 2021 on date and time in Groovy. There are a bunch of pathways in Groovy (and Java) for dealing with dates and times, starting with java.util.Date, whose limitations led to java.util.Calendar, whose complexities and frustrations led to Joda-Time (an Apache project), whose wise decisions led to java.time.*. So "writing about date and time in Groovy" could fill a small book.

In this case, two things led me to the desired article-sized explanation: First, Groovy is a great scripting language—a language with low ceremony that exposes many useful features in a compact and reasonable syntax and semantics. And second, I had a small and very specific problem to solve: how many working days between two calendar dates?

When I look back on technical articles I've written, I have consistently struggled when my topic has been too big or too unconstrained; I have consistently succeeded when I've narrowed in on a particular problem and gone ahead and solved it (and documented the solution).

This leads me to believe that, if I ever write a book, it will be a "cookbook," something like "130 Easy Recipes in Groovy".

What other things do you write about?

The rest of my technical writing could be lumped into project proposals and project reports. A proposal might be in response to a formal solicitation from a potential client; or it might be an unsolicited proposal, where we believe we have a solution to a problem a client is facing. A project report could be an interim progress report, which is more about project management and project status (and probably my least-favorite sort of writing) or a technical report, which in our case at least is typically describing the solutions we have found to a client's problem.

Our technical reports typically focus heavily on the client's articulation of their problem and are structured as:

1. Introduction
2. Description of (our understanding of) the problem
3. Brief description of the locale (our projects almost always deal with a specific locale or set of locales)
4. Summary of results
5. Recommendations
6. Appendices (including reference info, methodology, more detailed results, more detailed linkage of problem–locale–results–recommendations)

The idea is that the client should be able to have all the answers and recommendations required by the end of Chapter 5, ideally in ten to twenty pages. If the client is interested, wants more particular details or feels unconvinced, the Appendices should resolve anything outstanding.

How is writing a proposal different from other writing?

Proposal writing is an art, and not an art that I particularly enjoy practicing. However, I've written hundreds of proposals (yes, really) and I feel that I have learned some lessons along the way. For proposals that are formally solicited by the client, the first and most important lesson is to read the request for proposal over and over again until I have it memorized.

From the requirements and clues in the RFP I write an outline, typically with an introduction to the client and the problem, an introduction to our firm, then the most important section, which is "our understanding of your requirements", typically a table with the requirement quoted from the RFP in the left column and our compliance summarized next in the right column. After that comes a methodology section, followed by a project plan section, and finally an administrative section. Depending on the RFP, other typical sections (or appendices) are: our firm's experience; our team's individual and collective experience; and references.

I find that I tend to write from the "our understanding of your requirements" out into the rest of the sections—for example, if a particular statement appears in the RFP indicating some special preoccupation on the part of the client, it should be addressed in both methodology and plan. Also worth mentioning is that some RFPs, typically government procurements, provide their own structure which the proposal writer must follow.

One of the things we try to do in our firm is to do similar types of projects for the same or different clients; in these cases we can often re-use some or all of a previous proposal. In this way, our proposals have become a part of our "intellectual property", and we see the costs associated with them as a clear investment that we can better manage.

What tools and technologies do you like to use in your writing?

When I started my technical writing sub-career in the late 1980s, my tool of choice was troff with the mm macro set. Being a programmer as well, I used sccs to manage my version control problems and make to automate my publishing chain. My early web experience looked pretty similar except I was writing HTML directly in vi. So I've long been predisposed to markup languages and I've always seen them in the management and publishing context.

But for some reason, I've written every single Opensource.com article using LibreOffice Writer. Which is okay; it's a nice word processor and all. But I really should move back to a markup language basis, like Markdown or AsciiDoc. And I've moved on from sccs and make, so when I do make the switch to AsciiDoc source code control will be handled by git and the publishing chain by Gradle.

For work, I really need to interoperate with my colleagues, and we all need to interoperate with our clients, so that means (ugh!) Office 365. Since I don't use Windows, I don't have access to desktop-based Office 365 apps. In my experience, the web version is about powerful enough to be irritating; instead I use OnlyOffice for that. I used to use LibreOffice but my colleagues have pointed out that it leaves a whole other bunch of styles in any .doc or .docx that nobody understands nor appreciates.