Technical Writing

My name is Peter David Gustafson. I’ve been writing technical documentation since 2001 for technology companies of all sizes.

Your technical writing or API documentation project requires working with a proven expert who can bridge the gap between complex data and readability. Learn about my background.

I’m passionate about helping companies and programmers cut through the clutter managing the following types of projects:

  • Internal documentation architecture design
  • Authoring system design
  • UI/UX design and testing
  • Software user guides
  • API documentation

Internal Documentation Architecture

The mistake I see many companies make is ignoring documentation management. Every organization is different. So I’m not a big proponent of change for the sake of change. Although, upgrading your version control is a great place to start.

For example, I’ve worked on some projects where collaborators resort to old (easy) workflow habits. They rely on traditional paths such as chaining themselves to operating system file structures. Unfortunately, tethering your documentation to folders and files doesn’t support global access unless your writers have access through your VPN.

Regardless of access blockers, version control (i.e. Github, Bitbucket) is a must to manage updated content drafts across many writing teams. I’ve even seen some companies rely on using Confluence as their version control. If their organization is committed to Confluence, it’s smart to match their collective tool set.

Permissions are another issue. Some confidential projects I’ve worked on were closed environments. Therefore, relying on a public-facing version control resources such as Github won’t pass PCI compliance. In these cases, I recommend Confluence or even JIRA.

If your developer team manages projects using JIRA, it’s perfectly fine to tether documentation as a story requirement. Again, it depends on your organization’s software stack and workflow preferences.

Authoring System Design

There’s many authoring systems available. That’s part of the problem. Often, they streamline content development and management. Then offer output options such as HTML files.

My experience has been the best authoring tool is the one that streamlines production and exports it to the UI. However, this forces your prospective writers to possess specific software skills. Most savvy technical writers should be able to adjust their workflow to match your software stack.

The evolution of online content has forced organizations to hire front-end developers and UI/UX strategists as add-on resources. It’s expensive and honestly, adds too many creators into the documentation process.

What’s a better solution? It depends. Mostly on your users. How they interact with your online help content will impact how you craft and publish it for them. The simple answer is to bypass the content management system (CMS) approach. It’s not easy since many technical writers prefer to create within their preferred environments (i.e. MS Word).

Learn more about my approach to authoring tools.

UI/UX Design and Testing

Your user interface and experience is built by developers. The problem I see using this formula is it often overlooks management of users. Remember, your end-users are the lifeblood of your sales and revenue. So building a better user experience should be hardwired into your design.

Another issue is the fragmentation of contributors. Hardly ever are salespeople and relationship managers brought into the design process. The result is a user experience which doesn’t support the sales process.

In my experience, the more you can reverse-engineer your expected user outcome (i.e. find help documentation quickly, opt-in or make a purchase) the better your UI/UX will perform.

Software User Guides

They’re actually nearly dead. Drafting lengthy, long-form user guides are becoming a thing of the past. Users require instant navigation to pinpoint the answers to their problems in a few clicks.

Progressive companies serving millions of users do one thing very well: they treat help documentation similarly to their website sales content navigation.

The concept isn’t radical. As you progress users through your sales funnel, you lead them to content which builds trust and credibility. Perhaps even features and benefits along with customer testimonials (text and video).

Dynamic help documentation should follow the same path. Traditional software user guides (i.e. PDFs) don’t support this instant information-gathering requirement. Therefore, I prefer to develop a story-line approach whereby documentation is categorized on static pages. The fewer the pages the better.

Here’s a perfect example of a simple, yet dynamic help documentation by Stripe. As you can tell, navigation is limited to the section of the page you’re viewing. It’s by far the most elegant user experience.

API Documentation

Your company has likely built a dynamic software product or App. However, when it comes to building API documentation, too many technical writers lack the necessary programming skills and software expertise to manage your project.

Why?

Around 2010, many technical writers fell asleep at the wheel. As UI design and software documentation went into hyperdrive, these writers were forever left behind lacking the necessary skills to keep up with the industry. Specifically in programming skills. Great API writers (such as myself) are experts at the mission-critical elements of:

  • Working with the command line
  • Collaborating with programmers
  • Implementing single-source documentation architecture
  • Creating HTTP help documentation
  • Building logical graphics and tables
  • Producing video instructional documentation
  • Writing for all types of users

Your API documentation project deserves a technical writer with vast expertise in website design, file management and single-source architecture formatting to take advantage of a streamlined work flow.

Writing for all users while understanding their skill sets is critical. The following Stripe developer API screenshot gives you an idea of the types of content programmers desire along with code examples:

stripe-docs

User Profiling

Do you know your target documentation user? Often I find speaking with programmers can be valuable. However, remember that documentation is aimed to teach. Therefore, I like to evaluate your core target users and research their learning needs.

Translating what a seasoned programmer knows about your API needs to be reduced to the lowest common denominator of user knowledge. Successful technical writing and documentation is about helping users find solutions quickly. Fully understanding your user learning challenges is mission-critical to solving their problems.

Output Options

flareTraditionally, technical writing required developing documentation for many output formats and devices (i.e. desktop, smartphone, tablet, Word, PDF etc.) by creating separate projects for each type. Not anymore.

With the robust functionality of MadCap Flare, we can approach your project in a single source format.

Write once. Publish everywhere.

Doing so streamlines production allowing multiple outputs of documentation from a single source of content rather than separate sources for each type of output.

Another benefit is you can import native file formats into Flare from other sources such as Word, FrameMaker, HTML and other types of help authoring tools.

Doing so capitalizes on your current documentation file formats without the need to start from scratch.

Integration Issues

Granted, Flare may not be right for every organization’s server stack.

Integration requirements are always blockers. In these cases, I like to work with developers to find solutions that fit their technology rather than forcing authoring products which don’t play nicely with their backend.

Online content (excluding API documentation) can easily be managed within a CMS. But beware. Going bonkers with heavy content management systems isn’t always smart.

Often heavy and slow requiring the pinging of databases, CMS reliance can be detrimental to website speed. Don’t forget customizing your CSS to match your company branding will requirement management. When these struggles arise, I usually suggest a static file structure for help documentation.

There’s a few good options.

  • One is MKDocs
  • Another is Hugo

Although promoted as help documentation solutions, they do require using a lightweight CMS.

A third option, my favorite, is building lightning fast static pages minus the weight of a CMS. There’s some commercial products on the  market. However, thinking out of the box shouldn’t include buying a box of software.

Building static help systems isn’t complex. Well, you do need resources to host the .md files but any developer with a few years experience can manage it.

Pinpointing Problems

ill-analyzerSuggestionsProject managers are busy people. As a technical writer, my job is to not only manage entire documentation networks but also identify and fix broken links and missing content. It’s not brain surgery if you have the right tools.

What’s my secret weapon? Analytics.

As your documentation grows, one thing is certain: it will become scattered. It’s the nature of the business.

But not if you’re hard-wired with the right tool. From 10 to 10,000,000 documents, MadCap Analyze pinpoints broken links, missing data and provides rich data on user engagement (or lack thereof).

Hmmm…a technical writer proposing the use of analytics? Yes. In this day and age, gleaning enormous amounts of data is easy and beneficial to your documentation users.

The bonus is you can capitalize on data trends of user engagement in your marketing of new prospects.

Are you tired of spending time and manpower on usability testing? Who isn’t?

MadCap Analyzer is like employing a large scale documentation team (minus the steep payroll and excessive snacks) to scan and report compliancy issues as well as dozens of other content gaps such as:

  • Documentation identify issues for improved quality
  • Elimination of duplicate or unused elements
  • Identify ways to improve how content is developed and maintained

Technical Writing Visuals

pie-chart-256Recently I had a client who contracted me to write a complex user guide. The problem was they outsourced graphics and imagery to an overseas designer.

Despite my best efforts to collaborate with their graphic designer about visual needs, the project was delayed for months.

Why?

It was because of the segmentation of skill sets. By relying on a freelance designers, they were handcuffed to his schedule which was far from timely.

Too many technical writers lack graphic design expertise (unlike myself). Graphic designers aren’t writers. The result was my client created a communications gap. There’s nothing worse than waiting on graphic designers to supply deliverables.

My approach is far different than other technical writers..

  1. I possess more than a decade of expertise in graphic design (Photoshop, Gimp).
  2. Visuals (i.e. graphics, charts and photographs) need to be developed in conjunction with the text.
  3. Task scheduling should be self-contained rather than outsourced to multiple contractors.

Video Documentation

video-player2Are text-based documents outdated due to the evolution of online video? Hardly. At the root of every user guide, tutorial and software API document is one goal: educate people in clean, easy-to-understand steps.

However, you have an alternative with video. Not always (especially if local language translations are required).

I’ve worked with many clients who understand the benefits of converting help documentation into video demonstrations. In these types of projects, you need to evaluate the following considerations:

  • User video access: public vs. private
  • Public: YouTube is ideal and can be used as a marketing tool
  • Private: Wisita.com is the gold standard for privacy protection
  • Content: scripting, voiceover and screen footage
  • Production: video development, formatting and cost

Is video documentation right for your company? Perhaps. However, you want to avoid outsourcing your video production. The cost can be staggeringly expensive. My suggestion is to work with me since I’ve been developing video for many clients since 2007.

Progress Elaboration

Whether you’re in need of help documentation or user guide development, I recommend using progressive elaboration. Doing so breaks down your documentation into iterations. Each iteration results in:

  1. Defined steps.
  2. New incremental iterations.
  3. Builds upon greater functionality of previous iterations.
  4. Supports refinement of complex instructions.

My Background & Skills

For nearly a decade I was a senior account executive for a national advertising agency. By 2007, I witnessed the explosive demand of IT documentation and chose to branch out on my own. Read my full bio and resume here.