This page includes samples of some of my technical writing and editing work. When my work was covered by a confidentiality agreement, I wrote representations of the work I did instead of sharing the actual documents.

If you have questions about any of these work samples or want more information, please contact me with this online contact form, email me at This email address is being protected from spambots. You need JavaScript enabled to view it., or call me directly at 513-486-2421. I'll be happy to talk with you!

 

Software User Guides: MadCap Flare

I worked with another technical writer to create user guides for logging-while-drilling (LWD) software. The users were manufacturing technicians who installed and programmed the LWD software and associated equipment. My work included writing, developmental/substantive editing, and applying the company style guide. Later, I moved the content to Flare and added custom CSS to style the text and control image size.

This sample is from the user guide for programming the LWD data transmission system. The Introduction, Warnings, and three FPGA topics are active, along with the Glossary. To maintain confidentiality, I rewrote some of the steps, blurred the screenshots, and removed the PIC and DataFlash/NAND topics.

Sample User Guide for Programming the CAN Bus Master (.htm)

 

API Documentation: Whiteboard (a Node.js-based API doc generator), Markdown, and reStructuredText (rST)

This is example API documentation that I put together as I worked through Tom Johnson's terrific course on documenting REST APIs (http://idratherbewriting.com/docapis_course_overview/). The basis for this documentation is the fictional wiki posted at http://idratherbewriting.com/docapis_new_endpoint_to_doc/. I also looked at documentation for a few other APIs to improve my understanding, specifically Rotten TomatoesStripe, and Twilio.

I used Whiteboard to generate a neat and organized API doc set with code samples. Whiteboard is based on Node.js, but it uses Markdown files to render the documentation.  

Example API Documentation in Whiteboard (.html)

If you're curious, here's the same doc set as a GitHub wiki written in rST.

Example API Documentation in rST (link to one of my GitHub repositories)

 

Process Map and Office Procedures: Draw.io and MadCap Flare

This document set is from a process improvement project. We worked with a county government department to review and update their office processes and procedures. I was the editor on the project. Our deliverables were Microsoft Word source files, published as PDFs.

I always thought the project needed process map overviews to show roles, tasks, and handoffs. I also wanted to try Flare's image map function. So I used Draw.io to create a business process model and notation (BPMN) process map and export it as a PNG file. In Flare, I used the PNG process map to create an image map--clicking a task on the process map links to the Flare topic for the corresponding procedure. I also added custom CSS for the text in the topics.

The "Receive Correspondence," "Retrieve and Scan Correspondence," and "Read Correspondence and Draft Response" topics and the overview map are active. The other topics are wireframe templates.

Sample Process Map and Procedures for Replying to Correspondence (.htm)

 

Offshore Oil Production Handbook: Adobe FrameMaker

This handbook was part of a technical editing project I completed for an offshore oil exploration and production company. I substantially revised and formatted 120 procedures, policies, plans, guides, and handbooks. In some cases, I merged relevant content from sources like company emails and reports, then rewrote and refined the content to create a complete, organized document.

After my revisions, the documents were distributed for review, then came back to me to incorporate all comments. The company did not have a style guide, so I developed appropriate style standards and applied them to all documents. The documents were developed in Microsoft Word and published to the company SharePoint site. Later, I moved some of the content into FrameMaker.

Most of the documents were written for executive- and manager-level employees. However, the handbook excerpted in this work sample was available to all employees and contractors involved in well operations, from executives to floorhands.

This work sample includes my revised text for the first seven sections, with all company-specific and proprietary information removed. I replaced the text in sections 8 through 25 with lorem ipsum filler.

Sample Well Operations Integrity Handbook (.pdf)

 

Assembly Manual: Adobe RoboHelp

For this project, I wrote assembly procedures using videos as source material. The client recorded videos of their technicians as they assembled a large magnet used for a magnetic resonance imaging (MRI) logging tool. I wrote detailed descriptions of what I saw in the videos, then refined my descriptions into procedures. I also made notes to describe photo suggestions for illustrating different procedure steps.

I handed my draft off to an on-site technical writer, who walked through the procedures with the technicians and made corrections. The on-site writer also worked with the technicians to take photos to use as figures. An editor revised and formatted the updated procedures and added the photos as figures. I came back in toward the end of the project to help with final proofreading.

The manual was written for shop technicians. It was originally written in Microsoft Word and published in PDF. I moved some of the content into RoboHelp while I was learning a newer version of the program.

In this sample, the active topics are Purpose and Scope, Equipment and Materials, 1 Prepare the Lead Epoxy, and 2 Prepare the Magnet Assembly Machine. All other topics contain lorem ipsum filler. In the active topics, I rewrote some of the steps and blurred the figures to maintain confidentiality.

Sample MRI Logging Magnet Assembly Manual (6-in.) (.htm)

 

Work Practices: Microsoft Word, Markdown, and Wiki

For this project, I worked with subject matter experts (SMEs) in four states to create a manual with 90 work practices. The intended audience was electrical line workers. The company had been through several mergers, so work practices were often specific to only one state or referred to groups that no longer existed. We needed an updated manual that applied to all of the company's line workers.

First, I tracked down existing documents in company repostories, on local drives, and in binders on people's desks. Next, I worked with the SMEs to identify useful content in the existing documents and merged it into work practice documents that would apply to the entire company. The merged information was sometimes outdated or subject to new or updated regulations, so we updated the work practices as needed. I standardized the terminology across all of the work standards and eliminated duplicated and conflicting information.

I created a Word template that met the company's documentation standards and used styles to minimize the formatting burden. As we wrote the work practices, I created a project-specific style guide and document development guidance to help the client maintain the work practices after biennial reviews. I also helped the project manager refine the document inventory so that work practice titles accurately reflected their content. Finally, I wrote training and release notes to introduce changes to the manual's users.

This sample is a work practice for crew members. It explains the job briefing requirements in Occupational Safety and Health Administration (OSHA) 29 CFR 1926.952:

Sample Work Practice for Job Briefings (.pdf)

Here's a screenshot showing how I set up the work practice template using styles in Microsoft Word:

Sample Template for Work Practices (.jpg)

Just for fun (yep, I said fun), I reformatted this work practice into Markdown. I used StackEdit for the initial formatting, then fiddled around in the GitHub editor to add some GitHub Flavored Markdown (the little yellow triangles with the warnings). Then, I went back to StackEdit to figure out a manual table of contents:

Sample Markdown Work Practice for Job Briefings (link to one of my GitHub repositories)

I also blogged about how I created the manual table of contents in Markdown:

Tutorial: Manually Creating a Markdown Table of Contents for Your GitHub README (link to a blog post on this site)

And finally, I recreated the work practice as a GitHub wiki:

Sample Wiki for Job Briefings (link to one of my GitHub repositories)

 

Basecamp 3 API README: Markdown and Basic GitHub Documentation Workflow

To get a better understanding of basic GitHub documentation workflow, I forked the Basecamp 3 API docs repository on GitHub, edited and committed the README.md file, and created a pull request. Here's the original README.md file:

Original Basecamp 3 API README document (link to original Markdown document in my forked repository on GitHub)

Basecamp accepted my edits! I'm getting hooked on this open source documentation stuff. Here's the published file that includes my changes:

Published updated Basecamp 3 API README document (link to updated Markdown document published in the Basecamp 3 API docs repository on GitHub)

Sometimes it's difficult to see exactly what changed when the original text and the updated text are in two different files. Here's a version that compares my edits against the original text in a single file:

Edited and original text compared in a single file: Basecamp 3 API README (link to a commit record in my forked repository on GitHub)

 

Scientific Writing Articles

When I worked at BioScience Writers, I wrote articles to build rapport with potential clients and help researchers improve their scientific manuscripts. I wrote the articles in Microsoft Word, and our web developer published them in HTML on the company website. All of the articles I wrote were reviewed and edited by my wonderful colleagues at the company.

Some of the articles grew out of common issues that my coworkers and I noticed as we reviewed and quality-checked 30+ editing orders each week. Here are two examples:

Top 10 Basic Errors BioScience Writers Corrects in Scientific Manuscripts (link to published article on the BioScience Writers website)

Top 10 Good Habits in Scientific Writing (link to published article on the BioScience Writers website)

Some of the articles were inspired by questions people asked our company president during her popular scientific writing workshops. For these articles, I used her workshop slides and notes as source material and supplemented with my own research. Here are two examples:

Impact Factors and Your Scientific Manuscript (link to published article on the BioScience Writers website)

Writing Strong Titles for Research Manuscripts (link to published article on the BioScience Writers website)