Shrink the line between the branches of Writing

-

    There are several branches in Technical Writing. Some Technical Writers work in R&D and created technical documents. Some Technical Writers work with marketing and deliver product datasheets, brochures, and other marketing manuals. Some of the Technical Writers work on the e-Learning side and develop learning content for the product.

A technical document can also serve as learning material and marketing material if it covers the end-to-end scenario of using the product or a product feature. It must try to cover all the use cases with some real-life examples.

People want to scan through technical manuals rather than read them. Task-based writing and applying the principles of information mapping certainly helps in the same, but the document is less effective the bulkier it is. Users will find it harder to look for the information, and the information scattered here and there without any emphasis on the usage scenarios will not help either. Though you have comprehensive documentation, users will still find it harder to find the information they are searching for, or the information is too overwhelming for them to grasp. It increases people's frustration with the product and also will increase the number of support calls. The company will find it harder to market the enhancements to new customers.

Slimmer documents that are no bigger than a booklet covering the end-to-end scenario of how to do something are likely to be much appreciated by the customers.

Place equal emphasis on how easily people can find information in parallel with the completeness of it. Big technical manuals with thousand plus pages are hard to use and harder to maintain. The narrative of such documents is from the engineer's perspective than from the user's perspective.

The enhancement or new features that can make a big difference to the user must ideally have separate documents to help capitalize on what we have developed. The document can have engineering, marketing, and also learning applications.

Such a document must highlight the advantages of the enhancement/feature in all possible perspectives, such as security, ease of use, enhanced capability, overcoming the existing limitations, future-readiness, and others. Most importantly, it must cover the end-to-end scenario with some real-life examples wherever possible. It must serve as the single document the user needs to refer to for everything concerning the new feature. Consider the document organization and document size so that it will be easier to find information.

Several things help keep the document short and focused. Put summary steps for the scenario at the beginning, followed by detailed instructions for each step. Use information mapping techniques and use graphics very sparingly so that the feature maintenance will be easier. Consider using one single image or graphic file that explains most things about the feature.

The 'new' documents may help in convincing customers to pay more for the new enhancements. Announce the birth of a baby with a ceremony. Let the manuals serve as an invitation letter for the same. Sometimes you need help from documents to sweeten news that can come as a shocker for a customer. You may be ending support for an older version of the product and need to convince your customers to shift to a newer version. A well-crafted document can serve as a shield or a soft propaganda document. The document materials you develop need not be for just one purpose. It can help you market the product and also help train customers. It can serve as technical reference material for the future.

Title image from https://www.sentryone.com/blog/effective-technical-writing-is-essential-for-your-organizations-success

The ability to learn is the key to survival. We can learn faster by learning from each other.

Comments

Post a Comment

Popular posts from this blog

YAML front matter in Typora

-
Image
     I was looking for ways to add a cover page, header, and footer in Markdown and just figured out how we do it in Typora Markdown editor. It is easy. Set the header and footer using YAML Front Matter. The YAML front matter must be the first thing in the file and must be valid YAML, set between triple-dashed lines.  Source: https://support.typora.io/ The following is an example for setting the document title, header, and footer using YAML: --- title: Agile Technical Documentation header: A Quick Guide for Agile Technical Documentation footer: ${pageNo} --- Apart from this, you need to make a few PDF export settings. Select File > Preferences > Export > PDF and select the checkbox for Read and overwrite export settings from YAMAL front matters . Now, the document exported into PDF will have A Quick Guide for Agile Technical Documentation in its header and page number in its footer. If you need a cover page as well for the PDF export, paste the following content in the Ap
Read more

Technical Writing essentials

-
Image
     I want to share some of my learnings starting from the beginning days of my Technical Writing career. Everyone in the project must have a cursory understanding of the following, and the Technical Writer must understand it in detail: Language standards Learn the style guides. MSTP (Microsoft Manual of Style - currently called Microsoft Style Guide) is among the most widely followed style guides. You can access it online for free and even download the PDF for offline reference. See https://docs.microsoft.com/en-us/style-guide/welcome/ There are several other style guides, but it is mostly enough to refer only to Microsoft Style Guide. The following are some of the key takeaways: Avoid passive voice - sentences in passive voice are generally longer and harder to read. Use only the simple and easy words understood by the global audience with varying degrees of English knowledge. Your writing must have the same meaning for all people from different geographies and cultures. Never use a
Read more

Apply Goldilocks principle

-
Image
     There is one thing universal about successful managers. They keep increasing the performance benchmark every time. It applies to an athletic coach who wants to make his trainee globally competitive. I have worked under cruelly kind managers who are very ruthless in getting the tasks done. They push you to improve your competency and skills every day. You may have had a tough time working under this manager, and still, it is not something to be resented. Weathers the pressures work? We start looking for ways to do things better when the competitive edge is so narrow, and even a marginal improvement in something will give you an edge over your competitors. I had my dilemmas over if harsh managers are good or bad. A good manager sets difficult but attainable benchmarks and allows members to execute tasks with relative autonomy. There is no use flogging a dead horse. Spend time grooming the people who are motivated to do their best. I have spent time with people who do not have enough
Read more