Technical Writing Archives - pi Web Development

October 12, 2020October 12, 2020

Unprecedented

Juggling tennis balls — Photo by **Mochammad Algi** from **Pexels**

I keep hearing the word, “Unprecedented” in the news media and in conversations. This year is definitely unprecedented in the number of never before seen events. While this word is heavily utilized when describing the pandemic, hurricanes, fires, global warming, political/social unrest, etcetera – I prefer to use it for defining my personal approach to highlighting my services. Did you notice that huge shift from world-changing events down to me?

This is what we’re all doing. We’re trying to adapt our personal lives to a rapidly changing world environment. We’re asking ourselves, “How do I get from here to there?” From now to survival in the future. The answer? We take unprecedented or never before tried, approaches.

Marketing Me

My last post reflected on being flexible and adaptable to changing conditions. I’m juggling DoorDash, creative writing, technical writing, and website development. The goal is to have enough freelance website and writing work to support my creative writing, and only DoorDash when necessary. I currently have two clients:

Potential Finders – http://potentialfinders.com
Edmonds College Federation of Teachers – http://edcfedt.wa.aft.org/

So, how do I get more? Set up a storefront website? Advertise to big businesses? Pitch my services to every single person that comes along? Nada!

Focus

Here are the approaches I am taking with my bootstrapping as a freelancer:

Transparency – I’m a big believer in honesty and transparency. I have nothing to hide and I’m not going to pretend to be a big business. I am one guy with a few friends in the industry and a knack for learning what I don’t already know via the internet.
Target Clients – My clients are and will be those who don’t have a clue about putting together a web site. They don’t want to learn how to do it or try to understand it. They already have their nitch and they want a website to reflect it.
Personal Touch Marketing – Let’s talk! My marketing will be via contacts, word-of-mouth, and personal interaction. I want to know who you are and what you want to accomplish before I start talking numbers and timeframes.

The only thing that will not be unprecedented is business cards. I will have them in my shirt pocket, ready to hand out, to anyone who is interested. I will not be blanketing everyone I meet with cards. Only those who have expressed interest or need. That is how I roll.

So, is this an unprecedented approach to freelancing website development and writing? I’d be curious to hear what you think.

April 12, 2020April 12, 2020

API Documentation

da Vinci User’s Guide

From 1998 to 2002 I ran a small software development company called ETS, Inc. (Extended Technology Systems,) that specialized in custom software and consumer software for handheld platforms (Apple Newton, PalmOS, WindowsCE, etc.) We were doing a lot of PalmOS development in the C language and we decided to develop a tool for designing databases and API code for PalmOS. The product was called, “da Vinci” and we needed a User’s Guide. Even though I was the CEO of a small ten-person company, I was also the only writer on the team. So, I took on the task of producing the User’s Guide.

What happened to ETS, Inc.? This was an exciting and booming business from 1998 through 2001. However, the event of 9/11 had a major impact on the market. The day before 9/11 I was turning away business since I didn’t have the resources. After 9/11 the phone stopped ringing. Our existing clients tightened their budgets and quit spending. We almost had a bundling deal with Metrowerks, but they were impacted too, and quit spending. I poured my savings into the business throughout 2002 and eventually closed our doors in September of 2002. Many good lessons were learned and it was a good run while it lasted.

Target Reader

The target market for da Vinci was PalmOS developers. Almost all of the PalmOS developers at the time were using Metrowerks CodeWarrior for writing and compiling C code for Palm applications. We designed da Vinci to work with the CodeWarrior environment.

Document Layout

As with any software application guide, especially one for developers, I focused on these major topics:

What It Is.
Getting Started.
Tutorial.
How to Use the Application.
API Guide.
How to Get Help.

The guide needed to be easy to read, have visual cues and screenshots, and easy to follow steps. And the API section needed to clearly define each command, command structure, parameters, expected results, and related notes.

The Guide

The entire guide, as a PDF file, is available here for downloading and review. Even though this was written back in 2002, it is a good example of my technical writing experience as it relates to programming and API guides.

April 12, 2020April 12, 2020

Internal Git Setup Guide

An Example of My Process for Technical Documentation

A page from the Git Setup Guide — A page from the Git Setup and Usage Guide

Project

One of my roles at Averetek, Inc. (Now e2Open.com) was to provide internal technical documentation. The development team had been using Microsoft’s Sourcesafe and continued to run into difficulties. The decision was made to move all of our source code to Git and to use Atlassian’s SourceTree as the User Interface. Since this migration required a bit of a learning curve for existing and new developers, some documentation was needed. I was tasked with putting together a guide for using Git with our environment.

The Challenge

Due to the complexities of our development, sandbox, and production environment, combined with maintaining multiple code branches for multiple clients – this was not an easy transition to execute. It required very specific steps. At the time of this assignment, I was providing assistance with DevOps and I had a good grasp of the development systems and the process for pushing our code through the different environments.

My Approach

While outlining and writing this guide, there were some key items I had to keep in mind:

The target readers are developers. They are smart and they can quickly grasp the technologies being introduced.
Developers really don’t like to read a lot of documentation. They want to get through it and get on with writing code.
Pictures and Steps are good. The best approach to showing someone how to do something when you can’t be physically there is to give them a picture (or a brief video) of how to do it and provide specific and individual steps.
What if considerations. When writing an instruction guide the author needs to think about the “what if” questions that might come up. What if the developer does not have the correct permissions to see the source code? What if the screenshot in the guide does not match what the developer sees?

Test the Writing

One of the things I quickly learned when writing “Adventures in Flight Simulator” is to always, always, always test the steps and instructions after writing. I had a wonderful technical editor assigned to that project and he was great at following my steps and then highlighting something I missed. Not only do I try to test my writing, but I also verbally read it out loud to make sure it sounds correct.

Completion

While I am not able to share the entire document here, I wanted to write a post about it, and to highlight the things that need to be considered when writing technical documentation. It was a fun and geeky project for me. I felt a sense of accomplishment when the developers were using my guide to get them through the migration and back to their assigned tasks.