I spent a little over a year working as a technical writer in a software company that developed sales enablement solutions. It was my first job after completing my MBA and I was eager to re-enter the job market as quickly as possible. About two months into my role, it became obvious that technical writing wasn’t a good career choice for me. As a creative person who prefers to color outside the lines from time to time, I found technical writing too restrictive.
Still, I consider the time I spent with this firm immensely valuable. Looking back, it was a gateway into the world of software where I gleaned unique insights about how tech firms operate “under the hood.” I also learned about the specific challenges tech firms face when it comes to documentation. One of the more interesting things that I discovered was that user guides and other how-to-content are missed marketing possibilities for many tech firms.
User guides are squandered potential instead of a golden opportunity
Tech manuals are often wasted occasions because developers and mangers (who tend to have technical backgrounds) believe, erroneously, that these documents would be of interest solely to existing customers. They also believe that non-customers will find them more boring than staring into the great void of nothingness. While these documents are indeed very technical, a lot of people fail to realize that they can be tweaked in a way that strengthens existing partnerships and attracts new customers.
Instead of overlooking user guides and how-to items as purely internal documents, companies can repurpose them as marketing materials to showcase their expertise and establish credibility. If they’re well-crafted and informative, user guides and other content, such as tutorials and how-to-texts, can leave a favorable impression of their service offering and foster positive associations among readers, including non-users (read: prospects).
User guides take a back seat to development rather than being treated as a complementary asset
The problem with user guides is that software development teams rarely consider them a priority. Tech companies are fast-paced environments that usually place greater emphasis on product development and innovation. As a result, user guides tend to get pushed down the hierarchy of tasks until they’re so neglected they become the black hole of the company.
Rapid technology changes don’t help either – the tech industry evolves so fast that teams often can’t find the time to update them frequently enough. In the end, the information on user guides quickly becomes obsolete and inaccurate which annoys customers and may lead to all kinds of negative consequences.
Customers who get frustrated may be deterred from fully adopting the software; the added frustration may be just what’s needed to encourage them to explore other software options with cleaner documentation. Another adverse effect of outdated user guides are angry customer calls. Have you ever had to deal with irate customers? Not pretty. If too many of them reach out to customer support for help, these calls will apply additional strain on the company’s support resources and workload. Instead of directing users to user guides that contain up-to-date content, customer support representatives (or developers in smaller firms) have to stop what they’re doing and address problems that could easily have been avoided.
User guides don’t get updated due to a lack of cooperation between departments
Writing a quality user guide requires the cooperation of different departments, usually the developers’ team and the communications department (in some firms, especially small and medium-sized organizations, developers are expected to write user guides on their own on top of their code development tasks). When teams are segregated the way they are in a typical corporate structure, departments get siloed which results in limited communication between teams. Poor communication then spirals into a lack of coordination. Before you know it, the documents aren’t being maintained, leading to disjointed passages and content that doesn’t make much sense to anyone other than the author.
As I mentioned earlier, tech companies tend to prioritize tangible aspects of product development with limited resources going to documentation efforts. Due to this habit, companies are slow to hire writers or expand their communications departments, compelling developers and other technical experts to write specifications and other documents. But programmers generally lack the writing skills to present information clearly to a non-technical audience. For this reason, user guides are full of obscure, jargon-heavy content that users have a hard time understanding.
Lack of ownership doesn’t help either
If no specific team or individual is assigned to maintaining a document, it tends to get neglected and fragmented. With no presence of formal stewardship and guidance, everyone feels invited to pitch in. For example, the most recent update may be documented by a programmer who made a quick software patch; but then the bug gets properly fixed at the root of a faulty code and no one writes it down, leaving users scratching their heads as to why the solution doesn’t work as described.
When user guides are improperly managed, a number of negative consequences can emerge, including inconsistent standards and incomplete information. So, why does this happen? It happens due to:
- Inconsistent standards.
One developer may write in one format and employ a certain terminology and style, while another developer might use another. Unsurprisingly, this lack of coherence breeds even more confusion among readers who come to expect a certain way of writing but then get frustrated when the style changes. - Focusing on user guides after the product is developed.
I understand why this happens – everyone’s on pins and needles wrapping up a product release and making sure all functionalities work as requested by clients. Still, this pattern of behavior leaves insufficient time for thorough planning and creation, resulting in documentation that’s incomplete and open to too much misinterpretation and misunderstanding. - Outdated or improper documentation tools.
Obsolete tools this can contribute to the mismanagement of user guides by hindering the creation, management and distribution of content. More often than not, however, not taking the time to implement the latest tools is a symptom of a bigger organizational problem. - Delayed user feedback loop.
If firms don’t actively seek input from users or gather enough insights and suggestions, user guides are unlikely to get updated with the latest information. This indicates that a firm is unaware of user challenges and requirements, which can be damaging in the long run. Without a grasp of user challenges, an organization won’t be able to establish how its solution can be improved and which areas need innovation; it also risks developing solutions that don’t address real needs of the company’s customer base. - Lack of time.
Developers work on tight schedules and they may consider working with technical writers to explain the functionalities a distraction. As subject matter experts, anything that takes developers away from their primary responsibilities may be viewed as a waste of time. Because they’re so busy, they may not always recognize the value of collaborating with writers. - Developers’ insufficient trust in the competency of technical writers.
They could find it hard to effectively communicate technical concepts to writers who don’t have technical backgrounds. And some may fear that, because of this, any efforts in the direction of creating user guides won’t yield accurate documentation anyways. - Blind faith in the easy navigation of the company’s software.
Some developers are inclined to believe that the software they produce is 100% user friendly. They wrongly assume that customers will figure things out on their own without the need for documentation or any further clarification. - Lack of belief in the value of user guides.
Programmers may not see much value in documenting processes that will become obsolete in a matter of weeks or months as software evolves. Proper documentation has a reputation for being a slow process whereas coding is perceived as exciting and hands-on, which can discourage engineers from working with technical writers in a timely, organized manner. - Insufficient briefing.
User guides generate a number of downstream benefits but they’re not immediately obvious. This is because developers aren’t usually briefed on how improved documentation can contribute to the success of the product they’re developing. If documentation isn’t given the same weight as coding, its benefits aren’t likely to garner much visibility. - Tension between writers and developers.
In many firms, there’s a lack of true collaboration between developers and technical writers, which sometimes results in incomplete or inaccurate documentation. It’s not uncommon for tension between writers and engineers to arise, causing bottlenecks in the documentation process. - Frequent employee attrition.
High turnover is common in the tech industry which is known for being dynamic, competitive and evolving at a dizzying pace. Firms constantly seek employees with upgraded skills while developers often look for jobs with learning opportunities or companies that enable them to work on exciting projects. When employees in charge of documentation quit, the firm loses internal knowledge which further hampers any efforts to maintain and update content. - The firms’ reluctance to adapt.
Many companies have deeply ingrained norms that can slow down the adoption of new ways of doing things, such as advanced documentation approaches. Resistance to change can leave outdated practices in place because teams don’t feel ready to embrace new processes. They’re anxious about the initial learning curve and possible friction points that can emerge with the adoption of new methods. - A lack of incentives attached to documentation.
For most employees in a software company, performance evaluation and rewards, such as professional development opportunities, bonuses and recognitions of achievement, are tied to development tasks. An incentive policy of this type is likely to discourage team members from dedicating their time to documentation efforts.
Conclusion
For a number of software companies, user guides are an overlooked advantage instead of a valuable prospect. Rather than reformatting how-to-tutorials and user documentation into marketing collateral, managers treat them as an unnecessary back office function. This happens because tech firms tend to place greater weight on technical product elements over creating sales copy. As a result, they neither expand their communication departments nor hire professional writers. Lack of cooperation between departments is also a contributing factor, as are inconsistent standards, frequent employee attrition and miscommunication between developers and technical writers.
Does this sound like your company? If the answer is yes, I encourage you to read my Brand Communications Handbook: From documentation to conversion – Harnessing user guides for high-impact marketing available here.
