10 steps for copywriting

 

10stepscopywriting

The power of copywriting is like beautiful beaches or mountains – it attracts audience towards your business.  In most cases, content writing and copywriting are thought to be the same but they are two different entities that complement one another. Content writing engages an audience by showing how a рrоduсt workѕ and whу іt іѕ a еxtrеmеlу good dеаl. A copy on the other hand аіmѕ at саtсhіng and holdіng thе іntеrеѕt оf thе рrоѕресtіvе buуеr and is used to make the sale. Copywriting and content writing should go hand-in-hand to attract the right kіnd оf audience.  Here are the essential steps for copywriting:

Hіghlіght уоur product’s benefits

Alwауѕ make ѕurе thаt уоur сору еmрhаѕіzеѕ bеnеfіtѕ оf your рrоduсt оr ѕеrvісе to the audience. People wаnt tо find оut how they can bе benefited. Thіѕ dоеѕn’t mean уоu tаlk thе fеаturеѕ. Thеrе іѕ a dіffеrеnсе bеtwееn fеаturеѕ and benefits. A fеаturе of аn expensive watch іѕ a pure leather wrіѕtbаnd. A bеnеfіt оf the wаtсh is thе ѕtаtuѕ уоu gаіn bу wеаrіng ѕuсh a nice watch. Undеrѕtаnd thе bеnеfіtѕ your рrоduсt оr service саn оffеr аnd еmрhаѕіzе these benefits tо your rеаdеrѕ for grеаt rеѕultѕ.

Exроѕе уоur соmреtіtоr’ѕ wеаknеѕѕ

Do you see wеаknеѕѕеѕ in уоur роtеntіаl rival’s wеbѕіtе? Dо уоu ѕее рlасеѕ whеrе уоu саn vastly іmрrоvе оn thе ѕtаndаrd marketplace? If you do see wеаknеѕѕеѕ іn thе mаrkеtрlасе then уоu have a grеаt start, and уоu have a роtеntіаl mоnеу mаkіng buѕіnеѕѕ on уоur hаndѕ. The nеxt step іѕ tо capitalize on thеѕе weaknesses, аnd tо еxрlоіt thе ореn door thаt they hаvе lеft fоr уоu. If уоu rеаlіzе thаt your соmреtіtоr’ѕ website dоеѕ not оffеr аn еаѕу еnоugh storefront, оr lacks essential customer service, уоu nееd tо make sure thаt these аrе hіghlу coveted аѕресtѕ of уоur оwn buѕіnеѕѕ. Once you сrеаtе a business thаt іѕ superior tо thоѕе аlrеаdу іn existence, even іf thіѕ іѕ only by twеаkіng fеw ѕmаll things, thеn уоu wіll nо dоubt begin to see growth оvеr tіmе. If you соntіnuе to perform a hіghеr lеvеl thаn уоur соmреtіtоrѕ it ѕhоuld оnlу bе a mаttеr оf time before уоur соmраnу оvеrtаkеѕ thеіr соmраnу іn terms оf оvеrаll success.

 Knоw your аudіеnсе

Idеntіfу thе tаrgеtѕ that аrе interested in thе ѕubjесt аnd wrіtе ассоrdіng tо thеm. Knоw уоur аudіеnсе fіrѕt, аnd thеn wrіtе tо thеm. Knowing whо your аudіеnсе wіll help уоu сrаft a mеѕѕаgе thаt will rеасh out tо them. If уоu kеер уоur аudіеnсе іn mind, уоu’ll bе аblе tо сrаft сору thаt wіll reach out to them. Alwауѕ bе сlеаr. Dоn’t assume thаt your rеаdеrѕ knоw everything. Be concise аѕ muсh аѕ роѕѕіblе.

Cоmmunісаtе hоw customers are benefited

Mаkе a list оf аll thе features оf уоur рrоduсt оr ѕеrvісе. Emрhаѕіzе thе benefits, аdvаntаgеѕ аnd whаt mаkеѕ іt unіԛuе. Arе there аnу unuѕuаl tесhnоlоgісаl fеаturеѕ or сuttіng-еdgе techniques? Iѕ уоur іnvеntіоn оr the ѕtуlе оf the ѕеrvісе уоu рrоvіdе drawn frоm your own life еxреrіеnсеѕ? Cоnnесt your сuѕtоmеr’ѕ dreams with thе bеnеfіtѕ of your рrоduсt or ѕеrvісе and demonstrate hоw уоur рrоduсt оr ѕеrvісе саn hеlр tо ѕоlvе оr іmрrоvе thеіr ѕіtuаtіоn.

Use ѕесоnd реrѕоn, nоt first реrѕоn

In grаmmаtісаl tеrmѕ, fіrѕt реrѕоn, second person, аnd thіrd реrѕоn rеfеr to реrѕоnаl рrоnоunѕ. Thе second person роіnt оf vіеw is ѕuіtаblе fоr thіѕ tуре оf wrіtіng. Wrіtіng in thе second реrѕоn requires the use of thе рrоnоunѕ уоu, уоur, аnd уоurѕ. This роіnt оf vіеw іѕ uѕеd to аddrеѕѕ thе аudіеnсе іn tесhnісаl wrіtіng, аdvеrtіѕіng аnd copywriting.

Research уоur Subject

Yоu muѕt bе соnvеrѕаnt with thе niche you аrе writing іn аnd thе necessary kеуwоrdѕ tо rеасh your tаrgеt аudіеnсе аnd bе оn tор оf ѕеаrсh еngіnеѕ. Rеѕеаrсh аnd be conversant with уоur subject tо build аnd іmрrоvе уоur business.

Knоw уоur рlаtfоrm

The bеnеfіtѕ оf ѕосіаl media аnd social nеtwоrkіng аѕ a fоrm оf marketing cannot bе hailed еnоugh. Wіth tоdау’ѕ use of tесhnоlоgу, there іѕ nо fаѕtеr wау to reach a large numbеr of сuѕtоmеrѕ on a mоrе реrѕоnаl bаѕіѕ thаn through the use оf ѕосіаl mеdіа ѕіtеѕ such as Facebook, Twitter, Instagram, Linkedin and many others. Rеѕеаrсh аnd explore the right рlаtfоrm tо build аnd іmрrоvе уоur business.

Avoid tоо muсh information

Onе рrоblеm that ѕhоuld be avoided іѕ bombarding vіѕіtоrѕ wіth too muсh іnfоrmаtіоn. While іt іѕ еаѕу to want tо ѕhоw your visitors аll thе thіngѕ уоu аrе proud оf, doing it all at once will certainly ѕсаrе thеm away. In fact, presenting tоо muсh information in уоur copywriting wіll mаkе іt lооk unрrоfеѕѕіоnаl. Lеаrn to wrіtе vеrу unіԛuе соntеnt, ѕо уоu won’t ѕсаrе away уоur readers.

Inсludе a саll to асtіоn

Thе rоlе of thе саll tо асtіоn is to tеll уоur visitors whаt асtіоn thеу need tо tаkе nеxt, whеthеr thаt’ѕ dіrесt contact or hеаdіng towards thе сhесk оut wіth a shopping cart full of goodies and their сrеdіt card dеtаіlѕ. Tо do thіѕ еffесtіvеlу, thе саll to action hаѕ tо bе іn the active vоісе. Uѕе thе іmреrаtіvе. Mаkе іt асtіоn-оrіеntаtеd. Dоn’t let thе саll tо action turn іntо a dаmр ѕԛuіb bу рuttіng thоѕе twо wоrdѕ thаt аrе guаrаntееd to lose уоu аt lеаѕt 50% оf your audience – ‘click hеrе’. Use phrases thаt іnѕріrе, actually оffеr vіѕіtоrѕ ѕоmеthіng of wоrth аnd еvеn hаvе a ѕеnѕе of urgеnсу including time-sensitive offers.

Avoid empty promises

Give уоur rеаdеrѕ rеаѕоnѕ tо believe you. Put yourself іn the ѕhоеѕ оf уоur роtеntіаl clients. Whу thеу should rеаd уоur соріеѕ аnd whу ѕhоuld thеу purchase frоm you? It іѕ еѕѕеntіаl thаt уоu hаvе a gооd reputation оnlіnе ѕо уоu can easily реrѕuаdе оnlіnе uѕеrѕ tо bеlіеvе уоu and уоur рrоduсt.

 Prооfrеаd

After writing уоur соntеntѕ, the final step іѕ tо рrооfrеаd what you have wrіttеn fоr ѕurfасе еrrоrѕ ѕuсh аѕ grаmmаtісаl еrrоrѕ, misspellings, and рunсtuаtіоn errors. Yоur соntеnt muѕt be rеаdаblе and frее of thіѕ еrrоrѕ whісh wіll hеlр build trust in уоur products аnd services from your сuѕtоmеrѕ and readers.

Email info@ThomasEcafe.com or call us at +65-82086393 to create copywriting articles.

 

Tools for Technical Writing

Tools for (2)

  • Adobe FrameMaker is ideal for generating documentation in the PDF format. The look and feel of the PDF output from this tool is unparalleled.FM
  • Adobe Robohelp – Robohelp is ideal for generating Online Help. Every time you press F1 in any of your software applications, the help window that pops up is almost always created using RoboHelp. You can publish the files in the multi-purpose responsive HTML 5 format to view on any device.RH
  • MS Word – This is a basic tool and good enough for creating shorter documentation. This tool is  also ideal for companies which cannot afford to spend on expensive documentation tools like FrameMaker.

Email info@ThomasEcafe.com or call us at +65-82086393 to explore creating documentation in different formats for your application.

How to create a documentation plan

plan

A documentation plan lays down a blueprint for the whole writing project. As a writer, before you embark on your documentation project, you need to create a proper documentation plan and get it approved by key stakeholders. This will establish your credibility in the event of any crisis. It is important for you to study the marketing/customer requirements document. Ideally, the requirements document should state clearly the features to be documented, the depth of information to be included in the documentation, and the format (HTML, PDF, Word, etc). The next step should be to study the functional specification.

On the basis of MRD and the functional specs, the documentation plan should include the following details:

  • 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 can be multiple deliverable types needed, ranging from a single-paged addendum to a context-sensitive online help system.
  • Version control tool for managing the source files, for example, Snapshot CM, Rational ClearCase, git.
  • 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 2 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)
  • Doc approval process and approvers
  • Documentation delivery and distribution plan.
Main components of a Documentation Plan
  • COVER PAGE summarizing the name of the project; organization, and copyright or confidentiality statements.
  • Table of Contents – Proposed chapters and their tentative content.
  • An introduction that covers purpose and scope of the plan.
  • HISTORY (or REVISION LOG) showing the revisions the plan went through, with dates, the names, and titles of the persons who wrote different versions.
  • RISK FACTORS – What are the dependencies to complete the documentation? Which critical factors may bring this project to a halt? What are the impact (H/M/L) and the probability (H/M/L)? What measures should be taken for such an eventuality and who are the mitigation owners.
  • Reviewers and Review Process displays the names, titles, and contact information of the writer and all stakeholders involved with the documentation project.
  • Product features – what are the features that will be documented.
  • Document specs – Is this going to be an online document, a printed document, or both? Will it be single sourced? Will the project be using a client template? Which version control tool will be used for managing the documentation source files.
  • Schedule – What are the milestones in the development of the document? What is the effort required? When should the review cycle(s) be finished? How many rounds of reviews should be allowed? What is the start/end date for the whole project?

Kickstart every technical writing project with a well-crafted and an approved plan. Contact us at info@ThomasEcafe.com or call +65-82086393 to create a documentation plan for your project.

Why Hire a Freelance Technical Writer?

Hire a freelance Technical Writer

Why hire a freelance Technical Writer?

While the role of a software engineer is to develop applications, their days are consumed in creating technical documentation. It’s not a pleasant experience for engineers to create documents. For professional services, there are different sets of documents like UAT, Architecture document, Customer Requirement document, Design document, etc that need to be delivered to the customer.  In some cases, the content may be available but it needs to be formatted and edited. This is where freelance writers can play an active role by doing the documentation and letting the engineers focus on the development.

The majority of the companies hire Technical Writers as permanent employees and later retrench them when things go awry. This affects the company brand and the management can be labeled by potential job seekers as untrustworthy. Most of the companies’ documentation can be handled by a freelance writer.  As long as the company can meet the following conditions, the documentation can be done offsite.

  • An SME who can spend 30 mins daily via skype
  • The product/application accessible from the writer’s laptop,
  • A demo of the product/application
  • Access to the design documents/test plans/test cases.
Where to look for a freelance writer

This is the best site to look for a writer. We have a pool of professional technical writers, copywriters, editors, and designers dedicated for your projects. There are other sites also such as LinkedIn or Facebook, where you can find freelance writers. The greatest benefit of having a freelance writer is you save cost compared to hiring a permanent or a contract writer.

Writing is an art as well as science. Most companies hire a novice writer to save cost. If a writer has poor communication skills or imperfect grammar, it leaves a bad user experience. We will assign quality writers, with relevant degrees and experience for your project.

Visit www.ThomasEcafe.com, or email info@ThomasEcafe.com or call +65-82086393 to discuss your requirements.

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.
  • Distribute the plan to the core team members: PLM (Marketing), R&D lead (Engineering), and PM (Program Manager). Request them to review and approve the plan.
  • After the plan is approved, start Interviewing the SMEs to extract the technical knowledge. Ask the right questions in the right way to glean information from different personality types. Request for a demo or join the demo sessions that are given to the sales team.
  • Attend the core team meetings, interact with the application, study the design documents, ask questions to testers/developers.
  • Start writing the first draft.
  • Perform a peer review with other writers if possible.
  • 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.

Visit www.ThomasEcafe.com, email info@ThomasEcafe.com, or call +65-82086393 to discuss your writing requirements.

Advantages of Technical Documentation

Advantages of Technical Documentation

Generates awareness – Your primary goal as a biz owner should be to create awareness of your company, product, service or the benefit it offers for your potential audience. 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
  • Testimonials from happy customers
  • Reviews on sites like Facebook, Google
  • Advertising that draws attention to your content

Establishes trust – Product documentation allows you to establish trust with customers. If more people trust you, it will increase your sales. There’s a big difference between someone knowing your product/services and someone trusting you, enough to invest in you or buy from you.

According to Forrester Research, buyers today make their decisions before they engage with a vendor. They inform themselves using websites and social channels. Even when they attend product exhibitions, 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 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. 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  at each stage of the customer journey, supplying the right information at the right time to help customers make proper choices. Check this white paper about the impact of product documentation in content marketing.

Educates users –  Here are some of the commonly used content materials to educate 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 – This is another area where the documentation can guide users in using the product safely by providing appropriate warnings. 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.

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.

If you are looking for a writer to create technical documentation, contact Geenu Ann via email: info@ThomasEcafe.com or call +65-82086393 to explore different possibilities to achieve your goals.

How to write a White Paper

White papers are a favorite marketing tool for companies to sell products as solutions to their customers. The purpose of a white paper is to educate readers and help them make decisions in choosing the solution that suits their needs. In this case, the white paper becomes an excellent marketing and SEO tool that advertises the company’s products or services.

But writing a white paper is a challenging task. It involves an in-depth study of the product and its application, gathering information from the subject matter experts, and studying the product design documents. The objective is not only to convey information but to spark reader’s interest to engage him in reading the rest. Precision and clarity are the watchwords. Naked facts are not enough to invite a reader’s invitation to the rest of the document.

Here are the main guidelines for writing a white paper:

Interview the SME

Meet the product owner, understand the requirements, check the target audience, ask for a target date of completion, and get a brief demo of the product.

Research

After the preliminary discussion, do your own research. More than 70 percent of your time should be spent on study and research.

Writing

Once you gain knowledge, write the first draft, juxtapose words, and convey information that gives a richer experience to the readers. When you’re satisfied with the first draft, send it for review.

Review

Occasionally, the first draft may not meet the expectations. It can be due to many factors such as you might have missed certain features, or it might not have been discussed in the first meeting.  Take an appointment for a second round of discussion. This is when you will get a fresh revelation. Capture these intricate details and put them into your second draft. Over the years, I have learned that a writer needs a tough skin, for no matter how advanced one’s experience and career, expert criticism cuts to the quick, and one learns to endure and to perfect.

Publish

Once you have incorporated all comments, publish it in the Word or PDF format.

Principal components of a white paper

A good page layout – A good page layout ensures that language, graphics, and colors combine on a page to promote clear communication. Readers of the page will find it pleasing and easy to read even though they may not be conscious of all the page layout techniques.

A title that arouses curiosity – A good title is the title of a successful white paper. A good title is like coming to a house you have never been in before and having the owner open the door and say “Welcome”. A good title can make a tremendous difference in the early acceptance of a white paper.

Table of Contents – TOC help readers in two ways: 1. they outline the structure of the document and thus provide insight into the document’s organization. 2. they provide the page numbers for all sections and subsections, thus helping readers to locate parts of the document.

Background/introduction to the document – The introduction sets the stage. It normally includes the historical background of the product and establishes the scope of the product. In essence, the introduction is a road map, it orients the reader by providing a context for the reading. In short, the introduction prepares the reader for what will follow.

Graphics – Graphics are essential for conveying key information in the white paper. Readers will recall one impactful graphic long after they have forgotten a thousand words of text. Create visuals first, write text last. Graphics are more emphatic than text and should, therefore, be designed early in the writing process.

In addition, the following information should be provided for a white paper to be effective:

  • How the product solves the problem
  • System functions 
  • Benefits
  • Architecture
  • Evaluation criteria for choosing the product
  • Conclusion

Contact Geenu Ann at +65-82086393 or email info@ThomasEcafe.com to explore creating white papers for your product/solutions.

Case Study – Creating an Operation Manual

About the project

We were contacted by a Taiwanese based manufacturing company, to create an Operation Manual for the 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 were not able to visit the site, we were provided with the 3D and 2D designs to visualize the product. The best thing about this project was that we had a dedicated person on skype to share the product knowledge and liaise with Chinese Engineers at the site.

The document went through several rounds of iterations until it was satisfactory. The entire manual took about one and a half month to deliver. They also needed translation from English to the Italian language. That took another one week to complete.

The entire documentation was done remotely without visiting the customer site.

To explore creating a manual for your product, contact us via email info@ThomasEcafe.com or call +65-82086393.

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.

Our Writing Process

The majority of the documentation projects start out with a comprehensive inventory of the “features” a product consists of—the menus, icons, and dialog boxes of software. Although it’s certainly true that each of these items will eventually need to be documented, the problem with this approach is that it focuses more on the product than on the reader. As a result, the reader’s needs are subordinate to the idiosyncrasies of the product, resulting in the documentation that works only for people who already knows how everything works and is interested only in finding out a few details. A feature-based approach is apt for reference manuals, where the objective is to provide information on something the reader already knows. But it works poorly in user manuals, where the goal is to teach the reader how to do something. The users who want to learn how to do something requires considerably more context than a feature the list provides. A layperson needs a broad overview of what they can accomplish with the product, the main components that permit them to accomplish these goals, and how all the components fit together. More experienced readers already know something of this overall context, and instead, need more intermediate-level information, as well as a comprehensive view of the goals they can accomplish with the product. Lastly, all readers need to know the specific tasks that must be performed in order to reach each goal. Below this comes the finest level of detail: the steps required to complete each individual task.

Here are the some of the rules that must be followed while writing:

  • Provide Broad-scale Context – Although the most documentation does an adequate job of describing the software features, the broad overview that shows how they fit together is often lacking. The documentation focuses too narrowly on tasks and procedures and, in so doing, fails to provide the larger goals that would help readers understand why they should perform the tasks and how each task fits within a broader understanding.
  • Provide Intermediate Context  – Having defined the broader structure of the document, the next step is to define the intermediate level of context for each of these groups: the tasks that, taken together, allow the user to accomplish a larger goal.
  • Provide Low-level Context – At the lowest level of our hierarchy of context, we must provide information that guides readers in their use of tools and procedures. In other words, we are not just helping readers use the product’s tools, but helping them use these tools effectively.  The trick is to choose an appropriate level of detail. The approach discussed thus far ensures that your documentation meets the primary goal of any documentation project: providing enough understanding of a product that users possess the necessary intellectual tools to plan an overall approach to using the product and can determine all the tasks necessary to attain each of their goals. But,
    ironically, the problem with this approach is that by focusing so strongly on the reader, it may neglect the product itself. As a result, certain key features of the product may be missed. This poses an obvious problem when the user encounters a feature, asks how to use it, and is unable to find any information on how to do so. The solution is straightforward: prepare a comprehensive list of product features and match it to the broad-scale, intermediate, and low-level contexts that you’ve prepared to ensure through your consideration of context that you have covered each feature. You’ll undoubtedly find some aspects of the product that you missed by focusing on the reader, and some of these may become new topics at one or more of the three levels
    of context.
  • Don’t Forget the Procedures – To prevent readers from being overwhelmed by a sea of text that conceals the procedural information, clearly, separate the context from
    the procedures. In an online document, this might be accomplished by means of
    hyperlinks. A short introduction beneath the main heading, perhaps as short as a single sentence and certainly no more than two or three sentences, provide, the necessary context for how to use this part of the documentation. technical-writing-process

Visit ThomasEcafe.com, or call +65-82086393, or email info@ThomasEcafe.com to discuss.

Technical Writing versus Creative Writing

Technical Writing is science as well as an art. It’s science because it behooves the writer to have an inquisitive mindset to study the domain that he might be encountering for the first time. It’s an art because it’s all about crafting the words to explain product features, installation procedures, operating procedures, troubleshooting, FAQs, description of UI labels, APIs, etc. keeping in mind the end users. It’s an art to decipher complex features and elucidate in a simple and user-friendly format to capture the reader’s interest. 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. The basic difference between technical writing and creative writing is captured in this infographic.

copy-of-our-writing-process

7 Critical Skill Sets for Technical Writing

The following core competencies you need to possess to succeed in technical writing:

  • Written and Oral Communication Proficiency –   Proficiency in grammar, usage, and mechanics is vital to a writer’s daily work. 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 learn 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 for documentation are Word, FrameMaker, and RoboHelp. Familiarity with Version Control tools is equally important.
  • 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. In a lot of cases, you have to think outside the box to find the solution.  Put yourselves in users’ shoes to get a sense of how they will use the product and what they are going to look for in the documentation. You want to communicate the message in the simplest way possible, but at the same time in a creative manner.
  • 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. In my research, the one skill that management craves above all others is for the writers to work well and excel in a team setting. Also desired is the ability to transform dysfunctional behaviors into more functional ones or to at least be able to operationalize problems, avoid distractions, and keep on schedule.
  • Interviewing, and listening skills – As part of your job, you must have an inquisitive mindset 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 meet up 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 minutes to digest rapid explanations.
  • Detail orientation – Pay attention to detail. Follow the approved style guides. Engage with several levels of editing to help your audience and to free your work of errors. A writer’s work requires quality control because it reflects directly upon the professional ethos of the organization. Proofread, proofread, proofread!