Categories
Business Documentation Process Training Writing

Importance of Documentation in a Pandemic

2020 has been one big, scary, and unforgiving roller coaster. The kind of roller coaster that you wanted to ride all of 2019 that you thought would be exhilarating, but once you buckled in, you realized you made a horrible mistake. The Coronavirus (the highest point of this metaphorical 2020 roller coaster) has impacted a plethora of small and large businesses, and in many cases has unfortunately shut many of these businesses down for good.

For the businesses that survived the seemingly never-ending upside-down loops that this roller coaster of a year has thrown at them, we have to wonder how they have managed to get though all of these changes. What resources do companies need to use to overcome the obstacles that this pandemic has brought upon them?

As someone who works at a FinTech company that survived and flourished during this pandemic, one of the most useful tools for our team members unsurprisingly had everything to do with documentation. Our company uses a software solution that provides a knowledge base that allows our team members to securely share easily editable policy, product, and company information, and give us access to new information as it becomes available. The virus changed many company procedures that were commonplace pre-COVID, and access to updated documentation was vital in making sure we were all “on the same page” and giving customers the correct answers.

Correct, easy-to-use, and up-to-date documentation is essential for any business, pandemic or not. Documentation allows for effective communication between teams and customers. Fewer mistakes are made and less misinformation is spread when everyone is informed about the correct information. Less time is wasted trying to find answers for a specific problem, resulting in a more efficient overall work flow and better customer experiences.

As we approach the end of this 2020 ride, it would behoove any business owner or company to evaluate where their company stands, and to see how documentation could improve overall success for their company and how to avoid paying the price of admission for any rides in the future. 

Categories
Documentation Language Writing

A Deep Dive into Technical Writing

As a writer – albeit these past 30 some years of technical topics – I believe words actually do have meaning and should be used carefully and correctly. So when I read recently in a LinkedIn post that a product manager had a “deep understanding” of his industry; or a post from my neighborhood email blast that a neighbor was looking to have someone do a “deep clean” of her house; or finally, that a webinar promised a “deep dive” into a topic; I knew something was amiss.

What’s up with all of these deep activities?

Why suddenly is an understanding of an industry insufficient that it now requires the adjective deep to make it somehow better? How does a cleaning of a house become more thorough by making it a deep cleaning? And a deep dive? Unless you’re discussing a scuba dive, what are you talking about?

The obvious answer, of course, is that corporate speak is to blame. People seem to need to misuse words to somehow make their lives more meaningful. Or something like that.

In technical writing, on the other hand, there is no “deep dive”. Or to put it another way, if you don’t know – don’t have a true understanding – of the technology you’re writing about, you’re wasting your time and, more importantly, the time of the poor person reading your useless work.

Because all good technical writing is a “deep dive”. To do less than that is not technical writing, it’s wordsmithing. And that is the biggest insult you can possibly hurl at a technical writer.

Categories
Business Computer Languages Language Marketing Process Training Writing

What Makes a Great Technical Writer

By Rachel Shoap

In a world full of individuals with such diverse skill-sets, interests, and passions, there are few who possess the expertise and chutzpa needed to be successful technical writers. The following list represents what I (a relative outsider to the field) think you need to possess to be a great technical writer:

  • Technical Aptitude: You know the old saying: “You can’t explain what you don’t understand”? Never was this truer than in the field of technical writing. If you don’t understand what you’re writing about, I guarantee no one else will either. You don’t have to be a software developer to describe how to use an app (in fact, that would probably be an impediment because you already know how it works). But you do have to understand how to use it to be able to describe the steps for someone to follow for that person to be able to use it. After all, the goal here is to communicate your knowledge.

  • Common Sense: Overthinking can be detrimental to one’s success, so it’s best to use the KISS (Keep It Simple Stupid) mindset, an acronym that I, as a salesperson, have taken to heart and that is now ingrained in my DNA. By using basic tech knowledge, and incorporating it into your writing process, you can become an asset to any company you work for.


  • Effective Communication Skills: How many times have you talked to a friend about something important, and she repeats what you said just to prove to you that she was listening, but can’t go into detail about what the conversation was about? I cannot stress enough the importance of communication in the technical writing industry. It starts with listening. Being able to listen to your clients’ needs and showing them that not only are you paying attention, but understanding and implementing those needs into the finished product (the deliverable) will build trust, surely fostering a long-term working relationship that will most likely result in repeat business.

  • Organization: The great Mark Twain once said, “The secret of getting ahead is getting started.” You can’t get ahead if you don’t even know where to start. Usually this inability to begin is a consequence of disorganization. Organization does not just mean making sure everything is in its rightful place, but mental organization and process organization: know what you want to say and have a roadmap on how to get there. Having a set organized process permits a technical writer to produce consistent results. There are always exceptions (client requests), but if you stray too far off the beaten path, then you’ll struggle to meet deadlines, which will lower customer confidence, and ultimately diminish your own confidence as a writer.

  • Declutter Your Mind: Clearing your mind allows you to become sharper and more focused. If you can’t get in the right mindset for work, your day will be full of procrastination and justifications as to why, for example, you’re taking a two-hour break when you just started working. People who can organize their thoughts and execute tasks promptly and swiftly can take on bigger projects with ease.

  • Empathy: As technical and methodical (and, let’s face it, sometimes boring) as technical writing can get, you may think that everything is written in black and white. But the ability to not only reach different audiences, incorporate those different backgrounds into your work and be understanding to the fact that not everyone can follow directions the same way – AND take that into consideration in your work – is a talent that is hard to come by.  Knowing your audience and knowing its needs can greatly increase your success when completing a project. Many companies struggle to get their intended message to customers, which ultimately leads to complaints and frustration on both sides.

If you are someone interested in starting in a new profession, or you are a client (potential or current) hoping to gain some insight and clarity as to what you should look for in a writer, then take these points into consideration. When you’re the spawn of a successful technical writer, whose business has flourished for over 30 years, you start to notice things.  Happy hunting!

Categories
Language Training Writing

Creativity in Technical Writing

By Rachel Shoap

To many people, just hearing the words “technical writing” evokes feelings of fear but mostly boredom. “What kind of person can tediously and meticulously write all day long while simultaneously lacking even an inkling of creativity and originality? I could never.” So said my technically (untrained) mind. Whenever I wrote in high school or college, my papers were riddled with profound metaphors and dialogue that formulated beautiful stories and character development that I was proud of. How could anyone choose to write technical manuals? They’re so bland! How could they knowingly choose a topic and style of writing that prohibits that creative flare that most of humanity longs for?

What exactly do technical writers do? For the most part, they put together information, precisely explain the significance of it, take the reader through the necessary steps to complete a task, and disseminate it to the masses in a way the masses can understand. This got me thinking. In its own right, technical writing has to be relatable and at the same time diverse. A technical writer has to strategically relay information while considering the mindset of the consumers of that information, as well as their ability to follow directions.

My ability to understand and dissect information presented to me may be completely different than Barbara’s, the 72-year-old grandma whose grandkids bought her a new cellphone for Christmas. Technical writers are tasked with making sure the information that they provide to consumers is relatable while making sure it is accurate and easy to follow.

Making something “easy to understand” truly takes inventiveness to another level. The ability to take this most technical information and make it understandable for people from different backgrounds, educational levels, and ages calls for the most creative of writers, even if writers that meet the social standard of creativeness do not think so.

Categories
Uncategorized

API Documents That Developers Love

Inevitably, during our first discussion with prospective clients about documenting an API, we are asked if we can do “something like Stripe’s”. Unfortunately, until recently, our response was “not really” because Stripe had created its own tool to publish API documentation.

Now, thanks to the hard work that people have put into open source projects like Redoc and the Open API Specification, we can finally say “Yes” to these requests for API documentation. Previously, three-column, responsive, web-based documentation was only available as part of an expensive subscription to a development platform or as a customer-developed portal, but as REST APIs have become more and more popular, the tools to support their development and use have become more widespread. We can provide three-column API specifications with a basic quick start guide hosted on our client’s own website. For the client, that means no recurring fees and no commitment to a development pipeline that may not be a good fit for its company.

For many of our clients, we are able to use their existing API documentation (with some editing), translate it into the Open API specification, and add any additional content (for example, how to build a basic application). At that point, using Redoc, it’s a simple matter of generating a website that looks something like this:

 Redoc-ScreenShot

With this three-column format that organizes navigation, technical specifications, and examples, it’s easy for developers to find and understand the features of your API. And, as we all know, “easy” often means they, the developers, are more likely to use your API over one that isn’t. Clearly, as they say in corporate parlance, a “win-win”.

 

Categories
Business Flare Process Tools Training Uncategorized Writing

When the Best Solution Is Not the Right Solution

If, after examining and analyzing a problem, I find the best solution, I recommend and, at times, fight for that solution. This approach seems so self-evidently correct that I’m shocked to find myself even writing it.

Continue reading “When the Best Solution Is Not the Right Solution”
Categories
Business Process Tools Useful Links Writing

Single Sourcing: A Case Study

Single sourcing, according to the ubiquitous Wikipedia, is a “content management method which allows the same source content to be used across different forms of media and more than one time.” (http://en.wikipedia.org/wiki/Single_source_publishing). The benefits are obvious: the maintenance and editing of the source content have only to be done in one place at one time, thus making the editing process more efficient (quicker) and less prone to error. Most technical writers have become single source evangelists because we don’t want to spend our time editing the same piece of content in exactly the same way in several different places. It’s boring, it’s inefficient, and it’s expensive. Root canal surgery (with the right anesthesia) would be preferable.

Continue reading “Single Sourcing: A Case Study”
Categories
Business Process Tools Training Uncategorized Writing

Technical Editing

T.S. Eliot dedicated the “The Waste Land,” arguably one of the most important poems written in the 20th century, to Ezra Pound for his timely edits. According to Richard Ellman, Pound persuaded Eliot to remove several poems that Eliot had inserted between the stanzas of “The Waste Land.” As Pound said, “the longest poem in the English langwidge [sic]. Don’t try to bust all records by prolonging it three pages further.” (From “The First Waste Land.” In Eliot in His Time: Essays on the Occasion of the Fiftieth Anniversary of The Waste Land.” Princeton, Princeton UP, 1973.)

Continue reading “Technical Editing”
Categories
Business Process Tools Training Uncategorized Writing

Tools of Technical Writing

As technical writing consultants, our job is to advise and recommend. Of course, that advice and those recommendations cover lots of different aspects of the entire process. Obviously, we review the material and try to organize the information so we can present it in the most effective, most efficient way possible. Rarely, if ever, do we receive much push-back from our clients on this part of the process. After all, that’s why they hired us.

 

And while writing and organizing content remains one of the more important parts of our work, we also believe that we have some insight into what tools to use make that efficient presentation of material possible.  Unfortunately, our clients don’t always agree.

Here are some examples.

A company approached us with a problem. It produced a piece of hardware that it sold with optional modules. The company wanted to ship a manual that covered only the modules that were purchased, not all of the modules offered. The problem the company was having was that it had created the manual in Word and either it had to manually manipulate the document each time it made a sale – delete the sections for the modules that weren’t purchased and renumber the chapters and pagination – or send a manual with all of the features and text for all of the modules. Which always creates problems – “Why can’t I get this machine to do what it shows in Chapter 8?” Answer: “Because you didn’t buy the module described in Chapter 8!”

We suggested we import the contents of their manual into FrameMaker and use FrameMaker’s conditional text feature to mark the text that belongs to each module. In this way, we could mark whole chapters that related to individual modules, as well as words and paragraphs – in feature lists, for example, in the introductory sections of the manual – so the resulting document would reflect only those modules that were purchased. A brilliant solution, we thought, and so did the client. Happy client; happy consultant.

A different company talked to us about documenting a large enterprise software package that also offered different, optional modules. After discussing the application with the SMEs and reviewing the existing documentation (our due diligence), we concluded that the final document would be very large – it was a VERY large enterprise software application that did many things – with lots of graphics and screen shots and would not do well in Word. Furthermore, the client admitted that its clients didn’t always buy all of the modules and so would want the ability to offer a manual that only included the modules purchased.

Fresh off the previous consulting engagement in which we were able to address the hardware manufacturer’s similar problem, we proposed using FrameMaker and marking the sections describing each module as conditional text. Then, the company could produce a “customized” document for each of its sales. Not only would we solve the “purchased module” problem, we argued, but we could assure the client that FrameMaker would handle the large size of the document much better than Word because that was what FrameMaker was designed to do and Word was not.

Our contact at the company agreed with us but found little support with her management. Why? Management wanted to be sure it could revise the document without having to hire a FrameMaker “expert” and so wanted it done in Word. What about the optional module problem? “We’ll deal with it internally,” they said. Since in our line of work, the customer is always right, we wrote the manual in Word and regretted every minute we spent on it, knowing the resulting material was inadequate. Alas.

I’ve yet to hear of someone instructing a plumber as to what kind of wrench to use to fix a leaking faucet or tell a carpenter what type of blade to use to cut a piece of wood, or, as I’ve said before, told a developer what language to use to code an application. We hire experts and rely on them to advise and recommend the best way to solve a problem. Technical writers are the experts. Listen to their recommendations.

Categories
Business Process Training Uncategorized Useful Links Writing

Technical Writing: Clarity and Precision

Good writing is clear and precise. Good technical writing, to borrow a phrase from the young people, is totally clear and precise. Let’s be real: most people don’t bother reading technical documentation until they’re stuck and don’t know how to proceed. Enter this? Press that? “What do I do now?” Unfortunately for those sorry folks, their foray into the user manual or online help is often not a good experience. The reason: the explanation is not clear and/or precise. Such is the state of my chosen profession.

Continue reading “Technical Writing: Clarity and Precision”