Documentation has changed since I started in the 1980s. From print to online to interactive aids, the delivery has changed, but the need hasn’t. Good documentation is critical to make your product successful, no matter how intuitive and friendly the software, hardware, or service is.
Working for a company that treats documentation as an integral, crucial part of the product is great. But I’ve also worked at big and small companies that treated documentation as an afterthought. How do you tell you’re in that environment? Here are some signs.
You don’t have any standards
While corporate branding standards exist, no standards exist for what makes a document. You may even have a corporate marketing style guide, but technical writing needs its own.
Work with the other writers to develop rules specific to your audience. Then, pick a recognized style guide. The Chicago Manual of Style is good for general grammar and usage. Apple, Microsoft, or Google style guides are also good choices. Pick one and stick with it.
The writers don’t collaborate
Meeting with the other writers often happens when there is bad news — a layoff, a reorganization, or someone leaving or joining the group. You don’t meet to discuss issues and brainstorm solutions. You have style sheets and page layouts, but they’ve mutated over time, and the same company’s documentation has a varied look. When someone looks at two documents from your company, something seems off.
Peer reviews can catch many problems. These should include conformance with corporate brand and style and copy editing. Another thing that can help is to divide up the work. Some people (me!) like to create product specification tables. Another writer might be better at creating checklists or other job aids in addition to other work. Work together to get the job done.
There are no real schedules or planning
You never see — or create — a real schedule or plan. Sure, there’s an Excel workbook with dates when something is due. But there is no breakdown of tasks and deliverables. There is nothing to hang on the bones of a calendar. You’re a line item in the engineering plan. But where is the information on how you’ll work together to get the product ready for release?
Create your own schedules and document plans. Create a document project plan of your own and ask all stakeholders for feedback. You’ll get two types of responses:
- I don’t have time for this. Why are you bothering me? Take this as an opportunity to educate these folks. You want to make their jobs easier. You give them something to react against, where they can ask questions and suggest their own ideas and additions.
- This is great! We should do something like this for all products. You have allies now. Treat them as valuable resources. Once you have a plan and schedule, you can refer to it when asked where you are and your status.
You scrounge for software licenses
Software to produce good documentation can be expensive. There are low-cost open-source tools (Markdown, AsciiDocs, Hugo, and Jekyll). However, you do need more than familiarity to use them successfully. The support you’ll get from commercial software and services is often worth the cost of the software. And yet… Documentation groups often have to do without.
One option is to get basic licenses for all but one writer. Give that writer premium, platinum support, and let all requests go through her. It could be better, but it is a solution.
You spend more time and effort on workarounds than on writing
Layout, link, and display problems are ever present for technical writers. Sometimes, searching a support resource, Reddit, or Slack can get you writing again. Other times, you’ll need to spend money (and effort) to get something to work.
Try to justify the cost by showing how much time you are spending fixing issues and not creating content. It’s good to get your management involved, as you’ll need them to champion any changes.
Management doesn’t understand what you do, and you’re left out of the loop
If you get introduced as “Here is the guy that makes the books look pretty,” you have a big education task ahead of you. Part of technical writing is design. Ideally, you should have a corporate design to follow. But making things look pretty should be the least of your work.
Efforts to be included in planning and weekly project meetings and to be asked about decisions affecting your work are ignored. Push to be included. Justify it by pointing out how catching wrong information earlier is more efficient for everyone. Give the user perspective in the meetings. Often, engineering is more concerned with meeting the spec than making the product work for the user. That’s OK! Most haven’t had any contact with end users. They’re working towards making the specification real. The specification should — but often doesn’t — include user data or descriptions. This is a great chance for you to do that work and make it available to the product teams.
Management doesn’t offer support
Finally, we end on a critical resource. You have some tough choices if you’re told that’s the way we’ve always done it, and that’s the end of the conversation. I’ve seen this attitude from writing managers who have never written or managed writers. They have no real idea what you are capable of and don’t want to know. They’re there to check things off a list. I don’t know how to refocus them or motivate them to change. But ask yourself, if your manager doesn’t value your work, why are you still there?
Photo by Jan Mellström on Unsplash.