How tech writers can benefit the enterprise

The need for clear, concise documentation within a company is more paramount than ever. Customers don’t read any more, they use documentation. How should customers learn about how to use a product? Where can they find more information? Who should handle an escalated issue? Why are users ultimately doing what they do? All of this may sound like a no-brainer, but it’s a stumbling block for many, many companies.

Let me give a quick example of what I mean. I’ve been fortunate to work for a variety of tech companies over the last decade as a technical writer and documentation specialist -- places ranging from Google to Facebook to gaming companies and financial institutions. But what I’ve noticed time and again is a lack of documentation, particularly internal-facing documentation used within a corporation.

This lack of basic documentation is a major pain point for many companies, but half of them aren’t even aware that it’s an issue. When I worked for several Asia and Latin America-based companies, they literally had no word for "tech writer" in their language. That’s right, no word, no title, no concept of just what technical documentation entails and how or why their business needs it.

But even North American businesses struggle when it comes to generating and maintaining good documentation. At a very high level, there are two types of documentation every company should have: external and internal documentation.

External-facing documents explain a company’s products to customers, how to contact support, what they’re all about, etc. Internal-facing documentation is for use within a company, showing how different groups relate to each other, their processes, procedures, escalations and so forth.

Importance of Internal Documentation

Most companies understand the need for external documentation. After all, your customers need to know who you are, what you do and how to purchase your products. But internal documentation often gets neglected, frequently resulting in dire consequences. In fact, in my experience, internal documentation can make or break a company.

So what does internal documentation do for you?

The beauty of properly maintained internal documentation is that it solves many problems before they arise. It saves time. It saves money. It prevents confusion. But how?

An internally maintained documentation wiki with proper process documentation, organizational charts, contact information, escalation paths, design documents, technical specifications and more all provide transparency and clarity within an organization.

Think about it. If you work on an engineering team, how are you supposed to know what marketing or product management are doing in relation to your specific project? How do you coordinate hand-offs and how do you prevent duplication of effort? Word of mouth, an ocean of convoluted emails, and even an online ticketing system are not enough when it comes to maintaining proper communication links within a corporation.

More often than not, entire departments within a company will be out of sync with each other, running separate sprints, using different deadlines, sometimes even having widely differing views on the use of their own products. If a company’s employees are confused, you can bet their customers will be, too. This isn’t so much a trickle down effect due to a lack of information, as it is a rising tide of ignorance that threatens to drive both customers and employees away from a company that is perceived as disorganized, or worse, indifferent.

Also, when employees leave a company, key information is usually lost because no proper knowledge transfer was documented. Wouldn’t it make things simpler if there were an online, ongoing list of all projects that was kept up-to-date? Perhaps a wiki page of essential contacts. Even a brief high-level overview of how their processes and procedures work. Nine times out of ten these personal "trade secrets" from individual employees never get written down, let alone disseminated among their peers. And it’s essential, badly needed information. This type of content should not exist in a vacuum or a silo.

Turning on the Lights

All of this happens because employees are frequently in the dark about what’s happening in the rest of the company. An internal documentation wiki eliminates this confused babble by providing easy-to-understand documentation for everyone to see and use. Those are the key tenants of a good internal wiki. Something employees can see and use.

A centralized and well-groomed documentation wiki provides a single source of consistent truth within an organization. No more referring to chaotic email threads or verbal discussions misremembered from a previous meeting. A documentation site that consistently displays up-to-date policies and procedures for internal operations means that everyone in an organization always knows what they are doing and where they fit in the larger picture of their company.

The very process of conducting an investigation into an organization’s internal documentation often reaps many other side-benefits. Process holes and missing steps in internal processes often become glaringly clear when a company undergoes this kind of "documentation audit." It’s difficult to solve a problem that hasn’t been identified, and that’s what good documentation does. It identifies what works and what doesn’t within an organization.

You may be asking yourself, "Isn’t this all just common sense? Why wouldn’t a company want to be more efficient?"

Unfortunately, this is where we bump up against human nature. Corporations often focus so intently on their customers and their products (as they should) that they end up neglecting their own backyard. If internal documentation is considered at all, it’s looked upon as a luxury or something to do when they have spare time. This can get a growing organization into serious trouble.

Undocumented processes and procedures (aka "tribal knowledge") creep up in every company. Conditions change so fast, especially in the tech industry, that the only way to keep up is to constantly adapt and alter things for the better. Change equals life for any progressive corporation, but change without meaning or a plan is ultimately destructive. To adapt, we must know what we’re actually adapting from and what we’re transforming to. Good documentation makes this plain by identifying who does what and how they do their jobs within the larger group.

Tribal Knowledge

An unfortunate side effect of "tribal knowledge" is that it results in much of this crucial wisdom existing only in engineers’ or managers’ heads. Typically, no one has the time or bandwidth to properly document what’s really going on. And that’s no small danger for a growing business or even a well-established company.

This is a where a talented technical writer comes into play. Engineers and managers typically don’t have time to generate proper documentation. Every company I’ve seen that tried to push this documentation work directly on their engineers ended up regretting it later on down the road when it started to hurt productivity. It also sends the wrong message to employees, signaling that this is a supplementary task to add to their workload, not something that should be leveraged to actually increase productivity and save them time in their daily jobs.

Instead, a tech writer culls the "tribal knowledge" from subject matter experts and relieves them of the duty of communicating their work in print. This leaves engineers and managers free to do their real jobs. This alone is a major organizational and financial benefit to any company, but it’s only the tip of the iceberg in terms of what proper documentation can really do for a corporation.

Imagine not having to ask IT for technical support because a tutorial already exists for effectively troubleshooting computer problems. Or picture an organization that actually generates less email and chat conversations online because the escalation paths, processes and procedures are so clearly laid out on their internal wiki that they already have the answers to their questions before they ask them.

This is an idealized scenario, but it’s a level of perfection worth shooting for. Anything that makes a company more efficient, faster, more accurate and all around better is a win-win.

Fortunately, this isn’t rocket science. Any company can implement this type of internal-facing documentation so long as they adhere to the policies and procedures that they institute themselves.

One of the biggest benefits I’ve found from this approach to clarifying internal documentation is the effect it has on the mental health of employees. After only a month or two of having a well-maintained internal wiki, I’ve noticed engineers and developers much more relaxed and less stressed out. Relieved of the constant need to document their processes and changes on their own, they have more time to do what they do best.

And after all, isn’t that every organization’s goal? To be the best they can possibly be? Whether you’re a manager, marketer, developer or writer, a little well-placed text from a technical writer can go a long way toward relieving headaches further down the road.

All of the Responsibility, None of the Glamour

The lack of documentation is a massive gap that exists in nearly every company and is rarely brought up, let alone openly discussed. Organizations are also missing the massive benefits that clear, concise writing brings to a company’s bottom line.

One documentation issue I’ve repeatedly seen is that once the internal documentation is cleaned up, some managers seem to think all documentation problems have now been solved. Permanently and forevermore. As though the same issues that crept up before will not return and that employees will instinctively know how to maintain the wiki that has been set up for them. Sadly, this just isn’t so.

Once again, we encounter the hazards of human nature and the fact that maintenance of even a good documentation wiki is essential to prevent the inevitable chaos that will reoccur once people return to more "tribal knowledge" methodologies in which important things fail to get written down.

For instance, I’ve seen several companies that hired multiple tech writers to "clean up" their documentation. After a year or two, the company’s health vastly improved with the benefits of good documentation. However, because the initial problem of chaos and disorganization was "solved" and new incoming issues are being readily dealt with by a team of crack tech writers, it may give management the impression that the initial problem of disorganization has been eliminated.

You can see where this is going. The company downsizes their technical writer team, and lo and behold, the same problems creep up again over the next year or two. Once again, the company finds itself in the same boat it was in before. Lack of proper documentation, siloed information in people’s heads and a general lack of understanding regarding who should do what within each department. Then the company rehires a team of tech writers to "solve" a problem at additional cost that would never have returned if the original team of tech writers had been kept on in the first place.

Technical writing may not appear as sexy as compared to other occupations. It doesn’t necessarily have the glamour of constructing a new application or managing a few dozen people, but like a good immune system, it keeps the rest of the company body healthy. By quietly nipping problems in the bud and relieving other employees of the burden of trying to figure out how to document what and where, good tech writing keeps an organization from getting sick.

Additionally, I’ve found that many people are uncomfortable with writing in general. This is where a tech writer can shine and really improve other employees’ performance. I’ve been fortunate to work with some brilliant engineers who could build anything under the sun. Yet they were terrified of writing an email. No joke.

Simply by having a technical writer ghostwrite materials for them, edit their emails and write process documents of their work, the engineers were relieved of a burden that previously seemed insurmountable to them. They were freed up, once again, to do what they do best. To code and create in an uninhibited environment.

Long live the tech writers!

Mark Noce is a technical writer at BDNA in Silicon Valley. He’s worked for companies such as Google and Facebook over the last decade, documenting everything from databases to engineering to mobile games. In addition to technical writing, Mark also writes historical fiction, and recently published his debut novel, "Between Two Fires," with St. Martin’s Press. You can find him at marknoce.com.

Published under license from ITProPortal.com, a Future plc Publication. All rights reserved.

Image source: Shutterstock/Eugenio Marongiu