Documentation is very important to each customer but companies often see documentation as an afterthought, an add-on, or an extra that doesn’t bring in more revenue. As a result, updating product documentation doesn’t always get the priority it deserves.
In her article, How Out-of-Date Documentation Can Cost You, Your Brand and Your Company, Jacquie Samuels provides some insight on why treating documentation as an add-on or an afterthought can be a costly mistake. She goes on to explain how out-of-date documentation is really worse than providing no documentation at all.
Read How Out of Date Documentation Can Cost You, Your Brand and Your Company and then leave a comment here with your thoughts. Is documentation being shortchanged where you work? How have you overcome this misconception in the past? We’d love to hear from you.
As Tech Writers advance through their career, they are not prepared to market their documentation department, but as their roles grow in the company, they often need to be Tech Comm Marketers to ensure their department survives.
In his article, How to Market a Documentation Department, Robert King discusses how to market a documentation department, providing how-to information that could be helpful to those who find themselves in this position. He provides seven ways to market documentation team services to internal and external customers:
- Quality of your goods and services
- Stepping out of the box for your customers
- Saying yes to your customers
- Connecting with your customers
- Telling about yourself
- Showing Value Added
- Your full documentation team
As he adeptly points out, being a Tech Comm Marketer can be very exciting or frustrating, successful or disastrous, but it’s about effort and persistence that will pay off with new opportunities, not only for the Tech Writer, but the entire documentation department.
Read How to Market a Documentation Department and then leave a comment here with your thoughts. Are you doing the same marketing services to your customer?
The September, 2014 issue of Intercom, a publication of the Society for Technical Communication (STC), is devoted entirely to API documentation.
Experienced technical communicators know that API documentation is among the best paid fields in the industry. And, rightfully so. While most of us who started out in technical writing started with end-user documents, those who have a strong aptitude for programming often end up as API documentation specialists.
While Intercom is available with STC membership, someone has added the September 2014 issue of Intercom to Dropbox so it is available publicly (at least for the time being).
- What is API Documentation?
- How Do You Break Into API Documentation?
- What Factors Contribute to Good API Documentation?
- How Much Programming Do You Need to Know to Write API Documentation
- How to Write Helpful Code Samples
If you’ve been thinking about broadening your career path into API documentation, or, if you just want to improve your skills in documenting APIs, you may find the issue to be a valuable resource.
Related topic: Why Developers Write Horrible Documentation
The process of book publishing is clearly a group effort. The book may start with the author, but to get it from the author to the end reader means it also has to go through a number of specialists, like an editor, copy editor, book designer, typesetter, printer and others before it ever lands on a bookshelf. So why is the parallel process used to output technical publications primarily the responsibility of one person?
Longtime corporate publications specialist Alan Porter points out that the book trade is based on the premise that the artistic elements, the creation of the content and the design of the book are only individual components of an overall modular process, and that by treating those components separately, the business of publishing flourishes because the process is scalable and repeatable.
In his article, >Why Technical Publishing Shouldn’t Be Art, Porter explains how, by separating each of the technical publications processes into separate modules, each handled by a specialist with the applicable tools, just like the book industry, we can streamline and even automate the business of technical publishing. For example, those with the strongest design or layout skills would apply those talents consistently across all deliverables, instead of having each technical communicator design, author, edit, layout, proofread, publish, etc. It’s not only a more efficient model of delivering tech pubs, it would seem to provide the ability to improve the consistency and quality of final deliverables. It seems to make a lot of sense to us.
Read Why Technical Publishing Shouldn’t Be Art and then leave a comment here with your thoughts. Do you think technical publishing would benefit from the modular process Porter suggests? We’d love to hear your opinions.
Words are powerful. Headlines, tweets, you name it. The addition or omission of a single word can give your audience an entirely different perspective on the topic at hand.
We subscribe to Sarah Maddox’ excellent technical writing and fiction blog, FFeathers, and get an email notification when a new post is published. Recently, we received such a notification in our inbox with the subject line:
[New post] Documentation developers need to do their jobs
Our first thought? Maybe this was a critique of documentation developers who aren’t doing their jobs properly, who needed to buck up and get with the program. Seemed interesting enough. Previewing the post in email displayed the same title. But reading beyond the title revealed this wasn’t a critical piece at all. Instead, it was a post about the types of documentation that developers need to do their jobs properly.
Clicking through to the post on her blog revealed a slightly different title for the post:
Documentation that developers need to do their jobs
Well, yes. Exactly. Great, useful post. And really, even the email subject line and post title could have been interpreted either way. We are in no way criticizing Sarah, just making an observation on the power of words. We continue to highly recommend her blog, and we are long-term happy subscribers. In fact, we tweeted it to our followers. Read the article.
All of that got us to thinking about the difference one word can make in interpreting the context of a sentence or a title. In this example, a seemingly unimportant word that carried so much weight – that. A word that some grammarians/instructors even suggest you try to omit. What are your thoughts?
What examples have you seen where one word can convey an entirely different meaning? Do you now feel any differently about “that”? Is it more of an issue with today’s nanosecond-short-attention-span audiences? Please leave a comment.
This excellent summary article on TC World makes the assertion that:
“Technical communication is moving away from engineering and closer towards marketing and communications.”
The piece cites and summarizes the results of surveys to back up that claim with three overall observations:
- Good product information encourages users to recommend a product.
- High-quality technical information is a decisive factor in purchasing decisions.
- The vast majority or consumers research online before buying.
We don’t think the third item is a surprise to anyone. Researching online in advance of making a purchase is pretty much a given today. But have you given much thought about the extent to which technical communications can influence purchase decisions and grow sales?
Some of the findings include:
- More respondents (47%) used product information to learn more about a new product before they used it than to troubleshoot a problem (42%).
- 82% of those surveyed felt that high quality product content was essential to good customer service.
- 88.7% believed that high quality technical information is important or very important with regard to the purchase decision.
- 72% responded that high quality product content makes it more likely that they would recommend a product and brand.
Are any of these findings particularly surprising to you? What are your thoughts?
Great Documentation Can Save You Big Bucks When it Comes to Support
Over on his I’d Rather Be Writing blog, Tom Johnson recently published a post titled, “The Future of Tech Comm is Developer Doc“. Johnson has a point in that yes, it’s true that the latest mantra is pretty much “If an end user needs documentation, your app/program/whatever is not user friendly.” Okay, we guess. After all, end users aren’t know to even bother looking at documentation – they’d rather go through trial and error, pull their hair out and then get help through tech support or by consulting with another user.
But technical writers who can write developer docs have been in greater demand and have commanded better hourly rates and annual salaries for years. That’s because it’s harder to find experienced technical communicators who are actually comfortable with developer documentation or who have sufficient understanding of programming languages to communicate effectively with a developer audience.
That’s probably why developers are often called upon &emdash; or make the conscious decision &emdash; to write the docs themselves, which is certainly not an ideal situation. Don’t believe me? See Why Developers Write Horrible Documentation.
So does the future for technical communications professionals lie in developer docs? Well, you could probably make an argument that Johnson is a bit biased since he admits most of his work is in the SDK and API areas. You could also make the case that he has a first-hand point of view on the topic. But we think technical communicators who can effectively document APIs to a developer audience have always been in greater demand, so there’s nothing really new. Or is there?What are your thoughts on the future of technical communications? Is it time for technical writers to grab the bull by the horns and learn how to write developer documentation? Please leave a comment, we’d love to hear your views.
Sarah Maddox, author, blogger and technical writer, has been working on a personal open source mapping project that shows technical communications activities–events, societies and more–around the globe. Sarah, who is the publisher of the technical writing and fiction ffeathers blog, explains the project in her post, Introducing Tech Comm on a Map.
The map shows at a glance centers of activities for Tech Comm around the world. Zoom in, or click on a circle in the location of interest and voila: information with dates, times, address and mapping. Just zoom out when you’re done and go back to global view.
The map’s source data is maintained in a Google Sheets spreadsheet. The map is updated instantly with each spreadsheet. Three other Google open source tools were used in the project:
- Google Places Autocomplete widget
- Google Apps Script
Sarah says that she is planning to invite a few people to add more items and help keep the map up to date. She is also now working on v2 of the map and is looking for suggestions and ideas for enhancements and improvements.
To us, Sarah’s project is innovative and shows great promise for open source tools that are already available to make the world a better place. What are your thoughts on the idea? Please leave a comment below. She is looking for your feedback and invites you to leave your feedback on her post.
Darwin Information Typing Architecture (DITA) is an XML-based open standard that provides the technology foundation that controls and manages creation, translation, workflow and publishing of content. Its use in the technical publishing community has continued to blossom. But as most communications professionals will tell you, DITA is not without its headaches and drawbacks.
In this post on Content Wrangler, Mark Baker provides a very detailed look at potential issues with linking in DITA publications. He not only looks at direct issues to consider within DITA itself, his discussion includes consideration for usability and how and why humans read.
What are your thoughts on using links in DITA? Should you keep them inline with your content, place them in a table at the end or avoid them all together? Please leave a comment below with your thoughts and experiences, and let us know what you like and don’t like about using DITA.
Calculating the Financial Impact of DITA for Translation
As companies grow, it gets more and more difficult to keep track of processes used both for day-to-day operations and for contingency planning. When smaller companies start bursting at the seams the need for documenting processes is generally understood, but the task of actually getting the work done seems overwhelming and often gets placed on the back burner.
In her article, The Value of Documented Processes, writer and QA consultant Marcia Weeedon, examines five important reasons for taking the bull by the horns and getting the job done.
Read: The Value of Documented Processes and then leave a comment below with your thoughts. Have you had to tackle the challenge of documenting processes? How did you handle it and what value has that documentation provided to your organization? What other benefits has the process documentation provided that are not included in her discussion?
The Well Written SOP – Critical for Process Improvement
Page 1 of 812345...»Last »