Blog

First Technical Writing Job

Throwback Thursday posts in social media often deal with something from a couple of years ago, usually to make fun of how outdated some technical thing from 2015 looks to our 2020 eyes. But this week I’m going waaaay back. 

We’re talking 1987-1988. I was a very green tech writer on her very first full-time technical writing job. The company that hired me had a contract to supply documentation for IBM Santa Teresa Lab in San Jose. My first project was to write the Getting Started guide for the 11th release of DFSORT, a mainframe software tool for sorting datasets. 

Tight crop of title page for 1988 release of Getting Started software manual for DFSORT. Includes author name and document control number.
My first title page in a software manual!

Writing A Manual

I didn’t have any personal knowledge about mainframes, other than “don’t drop the punch card stack” (which I learned from watching a college friend waiting for computer time when we both attended University of Oregon). I knew a teeny tiny bit about sorting data —  a previous boss had shown me how to sort columns in Excel, so I at least knew words like ascending and descending and could build on that. I was part way through my tech writing classes at DeAnza, and knew how to write instructions for making sandwiches (a typical class project) so the idea of writing “instructions” didn’t scare me, but I’d definitely never written an entire manual by myself.

Most importantly (for me), I didn’t know diddly about how big companies like IBM operated, since most of my work experiences to date had been at small companies or small subsidiaries. (For example, I spent several months working as a desktop publishing contractor for 3Com in 1987, but the small documentation production team I worked with were the only people I interacted with.) Working for small, cozy, or family-owned companies didn’t prepare me for IBM at all.  The very thought of doing work for a company that big was overwhelming. Even in the 80s Santa Teresa was a sprawling campus with multiple buildings, and Sykes Enterprises Inc. (the company I worked for) only had a 6-room office suite on a middle floor in a typical San Jose office tower.

But I was a writer with a couple of bylines to my name, and I was armed with a journalism degree, half of a tech writing certificate, and a style guide. I enjoyed computer tech of all sizes, shapes, and languages, and I thought (and still think) that learning new software was fun. I had a talent for asking questions, and didn’t care if my questions made me look stupid just as long as I got an answer. As a bonus, at that time in my life I owned multiple blue suits complete with white shirts and the requisite silk scarves. So my employer shipped me off to team meetings, gave me a short deadline and a desktop computer to use, and crossed their fingers. 

1980s photograph of author in blue suit with white blouse and silk scarf. Hair is very 80s dimensional, round and curly, making her head look about twice its normal size.

Working with Engineers

Five foot tall me, still a little bit too un-California after less than three years in the Silicon Valley, with my inner-cynic still nicely tamed from growing up in Oregon’s relaxed attitude, and with more fluffy curls than the entire cast of Hair usually sported…I probably drove those poor engineers nuts with all my chipper, naive, air-headed questions. But I got it done. The engineers even liked my work and told my boss. 

Writing mainframe software documentation isn’t glamorous today, and wasn’t even back then. It got me zero street cred, and I had to fight hard to even get interviews for my next technical writer job. But I learned a ton about the documentation process, and I definitely learned about working with engineers during my time writing for IBM. I enjoyed the job itself and liked my co-workers. Best of all, just a few months in I knew I had found a type of work that I was actually good at and that was complex enough to keep me interested over the long run. 

Two pages from a programming manual talking about using keys to move around. All text, no screenshots.
The only sample pages I have from that first job. The product name has been edited out since at the time I printed these the book hadn’t been printed yet and was still considered confidential information.

It’s been 32 years since the first time I saw a manual page with my name in the credits. It’s been 32 and a bit years since my first big meeting with a whole team of IBM engineers, all armed with black pens and three-ring binders. But I still very clearly remember the senior writer who went with me to that first meeting asking me afterwords if I had any questions. All I could say was “Why were they all in the same blue shirt?”

Three Tips for Improving RFP Titles

A lot of government departments and corporations work hard at figuring out what to put in their RFPs, but spend little time thinking about the RFP title or the names of the documents associated with the proposal request. Clear posting titles can often be the last priority, especially when the RFP creators are busy thinking about budgets and deadlines.  

The result can be confusing to folks looking to answer RFPs. For example, this morning an RFP with the elegant name/description of “HOW15044 09/26/2019 11:50” was in my emails. Having absolutely no idea if this was anything my clients would want to know about, I downloaded the PDF (unfortunately named “Solicitation.pdf” so no hints there) and opened it. The request is for “Identification of <state name redacted> citizens not in the Labor Force” and is a 32 page document. How in the world would a company that does surveys of populations know that this RFP is something they should look into? 

Inbox screen shot

People who answer RFPs (or who find them for clients) spend a lot of hours (and hard disk space) on badly-named RFPs like the one above. And people in companies and government departments are constantly missing out on contacting the right people for their projects by giving files and RFPs unhelpful names. I subscribe to multiple state governments’ RFP emails, as well as to several services, and in a single day I will see multiple RFPs for “Application Software” and “Software Solution” as well as the always informative “SOFTWARE SERVICES” in all caps. 

If you are the person in charge of posting an RFP to your state’s website or to a mailing list, you can improve the quality of responses (and potentially cut the number of “what is this RFP about” emails sent to the person named as the RFP contact) by doing one simple thing: writing an RFP title that clearly explains what you want, so that the RFP gets the attention of the right bidders. 

Here are three quick (and easy to implement) tips for improving your RFP titles. 

  1. Don’t repeat the RFP number/system identifier in the title of the RFP. You have a limited amount of real estate, so use it for words that describe the service or product you want bids on, and not on how you identify your RFP in your system.  You should also leave the date and version number off the title since those don’t provide any information to the potential bidder. You can use those things internally during the writing process, but scrub them off the title when you post the final RFP.
  2. Put what you are shopping for at the beginning of the title and keep any department or identifying info for the end. In a list of open RFPs I was browsing this morning, the one titled “<County name redacted> Financial Business and Service Desk Assessment” would be better titled “Assessment of Financial Business and Service Desk” with the county name completely removed. (An exception would be to add the county name at the end as “for County Name” if multiple counties might be doing RFPs for the same service or product.) This title still doesn’t clarify what type of assessment, but it does come closer to being aimed at the folks who might answer it. Another example is “CDFA_STARLIMS_RFO_201911-001” where CDFA is the department name as an acronym and RFO stands for Request For Order; both of those could be removed from the title (along with the date/number sequence). That specific RFP was written to find a consultant who knows how to migrate from an outdated version of a specific software to the current version, and that state would have been clearer using the title a different state used (on the same day no less) such as “UPGRADE SERVICE FOR THE STARLIMS™ APPLICATION.”
  3. Don’t assume the people you are hoping will respond will know what your acronyms stand for. It’s easy when you are within a state (or a department or a company) to begin thinking that the whole world knows all the acronyms you use to save time and space. IFB could stand for “Invitation to Bid” in many states, but in Illinois it stands for “Illinois Farm Bureau” and outside the USA that acronym is usually reserved for the “Insurance Fraud Bureau.”  If spelling out the acronym will help your RFP be found by the right responders (i.e., Insurance people rather than Illinois farmers), then you should spell it out. 

In addition, keep in mind that heavy use of acronyms in the title can hide the fact that your title isn’t following my point #2 and being clear about what the RFP is actually soliciting. For example, one RFP notice that came across my desk was for “CWDC CRM DQ for OIT”  which was actually an RFP for a Salesforce solution. If the RFP writer had spelled out all the acronyms in the title it would have been obvious to the person writing the RFP that the word “Salesforce” wasn’t in the title, which might mean that Salesforce consultants would never even see that RFP.

Writing clear and useful RFP titles can greatly improve your chance of getting the RFP in front of the right companies. I highly encourage anyone tasked with posting (or emailing) RFPs to put time and effort into creating a title/summary that will clearly identify the exact product or service you are asking companies to write a bid for. 

Good luck with your RFPs, and please feel free to contact me if you need help with titles, writing RFPs, or writing RFP responses.  

REST API Documentation

I recently had the opportunity to write a short (about 10 page) manual on a specific REST API for a client. I’m still trying to find some spare time to edit out any confidential info so I can post a PDF, but hope to get that done this week.

REST API documentation is a growing area for technical writers. I’ve documented specifications before, and have documented software that used calls similar to REST to perform operations. But one thing struck me immediately about the sample docs I was finding online that were specifically REST API docs: they jump right in to tables of parameters. I saw almost zero text of the type I call hand-holding (aka guiding a newbie over to the swimming pool before throwing them in) and very little orientation (pointing out which part is the deep end, or where they need to swim to to get out, to use the same metaphor). And I just couldn’t do that to my audience.

My document has tables of parameters and values, but it begins with a “getting started” type of section to lead the reader to the pool, and has tips and introductory paragraphs throughout to orient the reader. It may not be the standard style for REST API docs (many of which are written by engineers and not just for engineers), but it felt like the right thing for my doc, since the audience includes managers and not just engineers.

Proposal Writing and RFP Monitoring

Seeing a posting for a “Proposal writer” job today made me realize I haven’t talked about one of my ongoing client projects. My client sells their two software products to city, county, and state governments, and came to me three years ago asking if I could provide them with some help in their RFP process.

I currently do the following:

  • Read daily RFP emails from state agencies and RFP aggregators.
  • Monitor state databases of open RFPs for states that don’t send email updates.
  • Identify opportunities to pursue. 
  • Review documents associated with the RFPs/RFIs, and summarize any issues or concerns.

I’ve also started a database of potential partnership opportunities related to the RFPs and will be helping the company to write “getting to know you” emails that they will send to a select group of potential partners.

If you’re looking for a similar service, or need help writing RFP responses, I’d love to chat with you. 

Throwback Thursday: Writing and Design of LeDoux Brochure

A throwback post today, about some brochure writing I did for a local client. At the time that Mr. LeDoux approached us about creating a brochure he typically marketed using humorous postcards with cartoon illustrations, so he didn’t have much in the way of content that could be repurposed. I took detailed notes at our initial meeting about what he wanted to convey, and wrote text geared to appeal to his target market. Since his postcards were humorous, I kept the tone light-hearted and casual. 

screen shot of brochure text
Initial draft of brochure text

We went through a couple of rounds of edits to get the text right where Mr. LeDoux wanted it. Most of the time when I do brochure writing it takes many additional rounds of revisions to get the combination of text and images approved, so I consider this one of my easy brochure writing projects.

Mr. LeDoux loved the design from day one. The only major changes from our initial mockup were to find a car photo with lots of blue sky and open road to use on the cover, and to tighten up the map we drew for the back cover. 

Here’s a slideshow of the final brochure and the first draft of the text.

The LeDoux automotive brochure was created in partnership with my husband, who supplied all the photography. 

Twitter Activity Analysis Tool

Are you wondering if the time you spend on Twitter (either marketing yourself or a company) is well spent? Thanks to Jane Friedman’s Electric Speed newsletter I’ve learned about a new tool that can tell you how much you’re using Twitter, what types of Tweets you’re posting, what hashtags you’ve used and whether you tend to repost or post all new content.

Account Analysis Tool

I think this tool is especially valuable for small- and micro-biz owners who do their own tweeting. For example, a business owner might discover they aren’t retweeting enough people in their business area, or that they only use hashtags that correspond to their favorite sports teams. Knowing little details like that might encourage the business owner to use Twitter differently. For myself, seeing that I’ve recently spent much more time on Twitter on Mondays has encouraged me to not let Twitter dominate the start of my work week — it was fine during the Christmas and New Years weeks, but now that we’re back to not having mid-week holidays I need to make sure I don’t let that become a habit.

Chart showing I'm more active on Monday
Screenshot of my Twitter activity analysis.

I like the interface a lot — it’s simple, clean, and easy to read. It provides enough information while not overwhelming you with too many types of information, and doesn’t rely on jargon.

If you like the tool you can follow the creator on Twitter for additional information, and he does offer Pro Accounts.

Review of Twitter Account Analysis Tool. http://crendo.com/2019/01/12/twitter-activity-analysis-tool/
Click To Tweet

Working Remotely

An interesting blog post from May on Technical Communication and Urbanization caught my eye this morning. I lived in the heart of the Silicon Valley when I started as a tech writer, but moved to be closer to family. You couldn’t pay me enough to move back, or to move to one of the other cities known for tech writing jobs. It’s not the cost that’s keeping me away (although that would be enough on its own). It’s the lifestyle.

Here in Salem I’m just over an hour from the coast. I’m a short drive from three of my favorite wineries, and can easily drive a little further to find more. I can get to Portland for a day or shopping, or make it up to Seattle for a visit with my cousins by dinner. I can head downtown and take the walking bridge to Minto Brown park, or hit up one of the many other parks in our area. I’m close to farms, to casinos, to beaches, to mountains, and to friends and relatives. My weekends are full of enriching experiences that make me a healthier and more well-rounded person. And this makes me a better writer, and a healthier employee/contractor.

Sign at a golf course on the Oregon coast.

TechCommGeekMom is right: “Urbanization is not a solution, it’s more of a problem. Digitization should be allowing for more widespread resources, not confining them to one area that everyone must flock to.”

Moving here hasn’t changed my skills or experience. I have the same degree, the same experience, and the same abilities. And thanks to the internet, I don’t need to be in the same room to do a good job for a client. The only thing I can’t do remotely is sit on a specific chair in an office in Cupertino, Seattle, San Jose, or some other big city. And all those hours each week the non-remote tech writers in big cities spend in traffic? I can spend those writing more pages, backing up files, taking a walk to clear my brain, or even cleaning my (home) office.

If you need a tech writer, don’t just look for one outside your front door.

AI and Tech Writing

Interesting article on the STC (society for technical communication) website.

“One aspect of AI that is often overlooked is the role of the technical writer. Amidst the appeal of new technology, technical writers serve a vital role in development of AI applications, including chatbots, by being the subject experts most equipped to address the content requirements of chatbots.”

AI, Chatbots, and Content, Oh My! (or Technical Writers Are Doomed—to Lifelong Employment)