Steps to Technical Writing

steps

  • Read the Marketing Requirements Document (MRD) and functional specification.
  • On the basis of MRD and functional specs, create a documentation plan that includes:
    • Product name, scope, and purpose
    • Milestone dates
    • List of documents that will be created and/or updated. If the project is about updating an existing product, list the features to be documented. If the project is about releasing a new product, additional planning is required. There are multiple customer documentation deliverable types a project could require, ranging from a single-paged addendum to a context-sensitive online help system.
    • Features that will be documented
      Work estimate and committed schedule for documenting each feature or completing each document
    • Committed documentation milestones
    • Documentation Reviewers including review schedule. There are several ways to conduct a review. Collect edits individually from each reviewer, or hold a review meeting to review everyone’s comments. Multiple reviews may be required. You can also use Adobe’s Shared review process to collect feedback from multiple reviewers.
    • Depending on the program, include any training material needed for the Launch.
    • Risks, assumptions, and dependencies. Include the following: Main risks of the documentation project (e.g. last minute feature additions), probability of each risk, Impact of each risk, Risk mitigation plan, Owner of the mitigation plan,
      Affected BOMs and/or document numbers
    • Doc approval process and approvers
    • Documentation delivery and distribution plan.
  • Distribute the plan to the core team members: PLM (Marketing), R&D lead (Engineering), and PM (Program Manager) who will review and approve the plan.
  • After the approval, create the draft document. Attend core team meetings, interact with the application, study design documents, ask questions to the testers/developers.
  • Send the draft to the reviewers identified in the documentation plan.
  • Update the documents as per the review comments, address all the major and critical documentation CRs and defects identified during the documentation validation.
  • Obtain the documentation approval from the designated reviewers/approvers.
  • Generate the final version.
  • Check in the final document into the build branch.

If you want to outsource your writing and documentation projects, contact Geenu Ann via email info@ThomasEcafe.com.

Case Study – Creating an Operation Manual for a Manufacturing Company

About the project

A Taiwanese based manufacturing company, located in Shenzen, China required us to write an Operation Manual for their PVD (Physical Vapor Deposition) Coating machine. The machine uses the Physical Vapor Deposition technique to transfer materials at an atomic level, based on the principles of magnetron sputtering, reactive sputtering,  using the fully automated coating process.

Methodology

Although we didn’t get a chance to visit the site, we got the 3D and 2D designs of the machine. The knowledge transfer was smooth. There was a single point of contact with a Subject Matter Expert, who was liaising with the Chinese engineers at the backend. He was available on skype daily to answer any questions.

The writing activity started in the first week of March 2017; we completed the first draft in the third week. The document went through several rounds of iterations until it was satisfactory to the client. The entire manual took about one and half month. Translation from English to the Italian language took another one week.

Here is the snapshot of the TOC for the manual.

1. ABOUT THIS MANUAL 5
1.1 Purpose and scope 5
1.2 Assumptions 5
1.3 Conventions 6
2. PRODUCT OVERVIEW 7
2.1 About the GTP-R Model 7
2.2 Equipment Working Condition 9
2.3 Reactive Sputtering Process 10
3. TECHNICAL SPECIFICATION 11
4. SCHEMATIC DIAGRAM 12
4.1 Machine Schematic 12
4.2 Electric Schematic 14
5. MACHINE DRAWINGS 17
6. SAFETY INSTRUCTIONS 20
6.1 Safety – Yours and Others 20
6.2 Safety Regulations 21
6.3 Noise Vibration 23
6.4 Safety Decals 24
7. INSTALLATION 25
7.1 Installation Safety Rules 25
7.2 Installation Process 25
7.3 Machine Parts and Functions 26
8. OPERATION 32
8.1 Overview 32
8.2 Operating Position 33
8.3 Pre-Operation Inspection 33
8.4 Emergency Stop 34
8.5 Standard operating Procedure 35
8.6 Electrical Control Mode 36
8.7 Operating the Machine 37
9. MAINTENANCE 42
9.1 Maintenance Items 42
9.2 Cleaning Instructions 42
10. CONSUMABLE MATERIALS AND SPARE PARTS 46
10.1 Consumable Materials 46
10.2 Spare Parts 49
11. TROUBLESHOOTING 52
12. WARRANTY 55
13. MAINTENANCE SERVICE RECORD 56

If you have any questions or need us to create a manual for your product, contact Geenu Ann, at info@ThomasEcafe.com or call +65-82086393.

Advantages of Technical Documentation

Benefits ofTechnical Documentation

Generates awareness – When your potential audience is not aware of your company, product, service or the benefit it offers, then the first goal is to create awareness. The key point here is to create content based on a set of keyword phrases and topics that potential prospects are already searching for online.

You can build awareness through:

  • Blogs, white papers, articles or infographics published on your site and third party media outlets
  • Testimonials from happy customers
  • Reviews on sites like Facebook, Google, and Yelp
  • Advertising that draws attention to your educational content

Establishes trust – The main goal is to establish trust. If more people trust you, everything else will fall into place. There’s a big difference between someone being aware of you (which is really hard) and someone trusting you, enough to invest in you or buy from you.

Buyers today complete from 60 to 90 percent of their buying decisions before they engage with a vendor according to Forrester Research (http://blogs.forrester.com/
lori_wizdo/12-10-04-buyer_behavior_helps_b2b_marketers_guide_the_buyers_journey). Until people make their decision to buy, they inform themselves using websites and social channels. Even when they attend physical events, they evaluate products and solutions on their smartphones and tablets. They avoid salespeople until they are ready. Content influences consumers’ impressions of a company throughout what marketers call the customer journey. At every step—not just after a sale—what buyers want is useful, authentic, relevant, accurate information that solves problems. Not fluff. Not gimmicks. According to a survey by IBM, almost 89 percent of visitors to IBM’s website for technical product information reported that high-quality technical content was either “important” or “very important” to their initial purchase decision.

Marketing tool – Marketing people need technical documentation to help them connect with their prospects and customers throughout the buying cycle, not just after the sale. Hubspot estimates that 60 percent of businesses employ content marketing—the creation, publishing, and sharing of content
to acquire and retain customers—as part of their overall marketing strategy. Effective content marketers know that they need to develop different types of content for each stage of the customer journey, supplying the right information
at the right time to help customers make choices they’ll be happy with.

Educates users – 
Newsletter — Weekly or monthly education that nurtures their interest
Presentation — in person or online, these allow prospects to learn as well as engage
FAQs — some people don’t like to read content, they just need the answers to their questions
Case Studies — some people just need to see that others have had similar situations and got the result they desired
Manuals – Most of the users of your product will definitely expect a manual on how to use or install the product.
Quick Start Guide – A shortened version of manual on how get the customers familiar with your product asap.
Troubleshooting –  This can be a standalone document by itself or part of the manual about how to solve problems in your product, by following a logical, systematic approach and make the product or process operational again.
Release Notes – This is a fundamental piece of information that should be part of your product release. It contains  version number, new features, issues, known defects, installation instructions, contact details, etc.

People want to be educated not sold. They will sell themselves if you just commit to educating.

Prevents legal issues – If by the misuse of your product, it causes harm or injury to users, you risk the legal action and can be sued by your customers. This is another area where the documentation can guide users in using the product safely by providing appropriate warnings.

Reduces calls to Tech Support – No company wants to spend money on tech support to answer basic customer questions. If the users are provided with the proper technical documentation, it will be a win-win situation for clients and companies, saving the time and effort of both parties.

Contact Geenu Ann via email: info@ThomasEcafe.com to explore how to create excellent content.

Thesis Editing and Proofreading Services

writing-editing-services

Common grammar mistakes:

Faulty Parallel Construction

A failure to create grammatically parallel structures when they are appropriate is referred to as faulty parallelism.

If you want your readers to roll smoothly along from one idea of yours to the next, use parallel structure.

Both of the following sentences essentially say the same thing. Which is easier to read?

  • He described skiing in the Alps, swimming in the Adriatic, and the drive across the Sahara Desert. (faulty parallelism)
  • He described skiing in the Alps, swimming in the Adriatic, and driving across the Sahara Desert. (parallel)
  • Formerly, science was taught by the textbook method, while now the laboratory method is employed. (faulty parallelism)
  • Formerly, science was taught by the textbook method; now it is taught by the laboratory method

Nouns should be parallel with nouns, participles with participles, gerunds with gerunds, infinitives with infinitives, clauses with clauses, and so on.

Sentence Fragments

According to the grammar rule—every sentence should be complete. Meaning, it should have a subject (the main actor/actors), verb (the main action) and, if applicable, an object (what the action happens to). Anything less is called a sentence fragment. With one caveat. Your meaning must be clear.
When a group of words is missing important information, it’s no longer expressing a complete thought. Following are some of the missing words: missing verb, missing subject, missing subject+verb, missing main clause.

Run-On Sentences

Here you will find more than one complete thought, each of which deserves its own sentence. This happens when the person gets excited about the subject matter and goes on at length without adding a period for quite a long time, and the sentence ends up sounding quite flustered and out of breath.

You must look for ways to break the run-on sentence into more than one. It’s all about keeping things clear and simple for your readers.

Dangling Modifiers

A dangling modifier has nothing to modify. It’s an error caused by failing to use the word that the modifier is meant to be describing.

INCORRECT: The experiment was a failure, not having studied the lab manual carefully.
REVISED: They failed the experiment, not having studied the lab manual carefully.

INCORRECT: Meticulous and punctual, David’s work ethic is admirable
CORRECT: Meticulous and punctual, David has an admirable work ethic.

Fixing a dangling modifier requires more than rearranging the words in the sentence. You will often need to add something new so that the modifier finally has a target word to describe.

Misplaced Modifiers

A misplaced modifier is a word, phrase, or clause that does not clearly relate to what it is intended to modify. In other words, a misplaced modifier makes the meaning of a sentence ambiguous or wrong.

INCORRECT: Andrew told us after the holiday that he intends to stop drinking.

In this example, it is not clear whether Andrew made this statement after the holiday or whether he intends to stop drinking after the holiday.

Split Infinitives

An infinitive is the form of any verb which starts with the word “to”—to go, to dance, to have written, etc.
Ideally, you are not supposed to split an infinitive by sticking extra words between the “to” and the rest of the verb. Contrary to what some grammarians say, there is no rule against using split infinitives in English. One might use them with care, but splitting an infinitive is sometimes the best way to clearly express a thought.

Infinitives should be split when the adverb either needs emphasis or wouldn’t work anywhere else in the sentence—for example:

They’re expected to gradually come down in price to about $50 to $75 each.

Placing gradually anywhere else in this sentence would create awkwardness and confusion.

Editing, proofreading, and formatting a can make a big difference to the clarity of your work and therefore the overall grade. Email: info@thomasecafe.com or call +65-82086393 for a quote.

What is Technical Writing

The primary objective of technical writing is to inform and instruct users in performing
a task or process or to acquaint them with a product. Technical documents are supposed to provide complete information on a product or system, albeit spread out in different formats e.g. PDF, HTML and document types – user manuals, operation guides.

The goal of writing is to convey complex information in a simple, understandable, and user-friendly formats to capture the interest of readers. Check this blog on 7 deadly sins of technical writing.

The basic difference between technical writing and creative writing is captured in this infographic.

copy-of-our-writing-process

How to become a Technical Writer

The following are the core competencies you need to possess to be a successful writer in your industry:

  • Writing skills –  Although most writers come from diverse backgrounds, one common trait is good writing skills. As technical writers, you must not expel raw materials but transmute it to provide what the reader most wants by steering away from dangling modifiers, run-on sentences, sentence fragments, split infinitives, etc. that can impede legibility or learning. The objective is to make the readers understand the topic quickly. The readers are not going to spend hours reading the document. A basic principle of good writing style is to abstain from unnecessary words. The shorter, simple words or expressions make your writing more concise and, consequently, make it look and sound more professional. Always provide a brief description of the subject followed by steps to achieve. Provide screenshots where possible. Another primary focus should be to improve your Template. Use numbering if the steps are to be performed in a sequential manner otherwise use bullets. The title and headings should convey the subject matter. The headings, steps, and body text should follow a consistent format.
  • Research skills – You must have a passion for research and new technologies. The technical writers are lifelong learners. The one hallmark of the technical writer is the acknowledgment of the room for improvement. There are plenty of domains for technical writing— IT, electronics, oil and gas, pharmacy, science, solar panels or digital gaming but we share the same passion, that is, curiosity.
  •  Learning new tools and technology – Writers must be willing to master tools that come across their way. The commonly used tools are Word, FrameMaker, RoboHelp, and XMetal. The writers should be familiar with DITA and the ins and outs of content management systems (CMSs).
  • Creative skills – Being a technical writer does not mean you stop being creative. There are creative ways to illustrate complex ideas in the form of graphic, video, and audio in addition to content.
  • Team building skills – No man is an island. Although, you may be a lone writer in the company, you must collaborate with SMEs, product owners, QA folks to accomplish your goal.
  • Interviewing, and listening skills – As part of your job, you must have the mindset of a detective to ask questions. At the end of the day, the most important Technical Writing principle is “If you do not know – ASK”. Writers are expected to ask questions until they are confident that they have the information needed to write content. Just remember, unanswered questions contribute ambiguity to the content and add risk to the business. You can gather information via different ways such as email, Skype, Adobe shared review process, or set up a meeting room to discuss and build consensus when there are conflicting opinions. You need to have good listening skills and allow the SMEs to talk while you take notes or record the meeting to digest rapid explanations.

howtobecomeawriter