Documentation Types

In the IT companies, there are different types of documentation created in the course of the product/project development. These documents are written by different authors based on their area of expertise: product manager creates the requirements document, QA creates test plan/test cases, architect comes out with design document, engineers come out with functional specification, and technical writers create the customer-facing documentation such as manuals, SOPs, white papers, etc. Below are some standard forms of documentation frequently generated during a product’s lifecycle. Under each type of document are some fundamental elements.

Requirement Documents (created at the initiation of a project, written by product manager):
This describes whom a product will serve and what it will do. It includes listing the users and how they would use the product, and for what purpose (also called use cases); a definition of the overall system architecture and development methods; a description of how the development team will do its work (what will be developed first, what might be added as additional features if there is time/money available); a schedule showing how long the development process will take; a concept of operations for using the product; a lists of participants, roles, and responsibilities; and eventually detailed descriptions of the data to be acquired and how it will be manipulated.

The audience is often information technology managers, who want to ensure that a development team knows what it’s doing, that resources are being used wisely, and that the work is proceeding according to plan.

  • Date and authorization
  • Project scope/overview
  • Task proposal
  • Proposal validation
  • Business goals
  • Specifications
  • Time and expenses
  • Resources and support.

Functional Specification Documents (created for Developers and written by Developers):

This communicates how things should be designed or built. Unlike requirements definition, which can be done without a lot of formal training in an engineering discipline, specification/design documentation usually requires hands-on experience with the tools, hardware, processes, and terminology needed to do the job.

These documents are often written by “engineers”.

  • Technical details of the product
  • Detailed tasks
  • Database design and schema location
  • Client needs
  • Program functionality
  • System platforms
  • User Interface
  • Security
  • Error messages.

User /Operations /Training Documents (created for guidance and instruction, written by Technical Writer)
This is the type of documentation most people are familiar with. It’s the PDF or online help module that people refer to when someone is looking for information. It’s a step-by-step process document that walks a user through the process of operating or employing a piece of software or an engineering product. User documentation often employs a dual-form organization, meaning it’s broken out by function, but is chronological when describing individual functions. It includes possible cautions and warning, which appear before a step is taken so the user is aware of a problem prior to taking any action. It establishes technical nomenclature and provides a glossary of those ever-present acronyms. It also ties the product’s functions with work functions.

To write user documentation, you have to become familiar with the user’s actual work processes: what their primary tasks/outputs are; how they normally encounter the product; how often they are likely to use it; how dangerous errors are if they occur and how they can be addressed; how do they handle exceptions or unusual situations; and what personal safety equipment (if any) they are likely to require to handle the product. In the space world, a payload user guide would tell a prospective payload manager about how they would go about delivering their payload to the rocket manufacturer, what sorts of interfaces they are likely to need, and what types of environments their payload is likely to experience during launch, and so forth.

User documentation is the best example of “translating technical jargon into English” and is often the most challenging and people-intensive technical writing you might do, as you must be able to absorb what the engineers are doing; advocate for the user if the product is creating problems, confusion, or dangers; exercise diplomacy when challenges arise between the designers/developers and the end users; write user test cases that make sense for the users’ work environment; operate as a guinea pig (test subject) for the user test cases; and keep the documentation updated as product/version upgrades arise.

  • Guide description
  • Product description
  • Installation and/or log-on procedures
  • Program functionality
  • Required information
  • Prompts and error messages
  • Trouble-shooting section
  • Glossary
  • Reference sheet.

Reference/Cheat Sheets (created as a quick look-up) contain:

  • Brief program overview
  • Brief explanation of each functionality
  • Quick ways to accomplish a task
  • Brief trouble-shooting section
  • Index and cross-reference sheets.

Quality Assurance/ Test Plan Documents (created for testing, written by QA) contain:

  • Program description and client needs
  • System requirements
  • Program accessibility
  • Functionality
  • Tasks and scenarios
  • Expectations
  • Regression testing
  • Problems and resolution.

SOP (Standard Operating Procedures) Documents (created for routine tasks, written by Technical Writers) contain:

  • Purpose
  • People involved/affected
  • Guidelines
  • Revision instructions
  • Procedures
  • Appendix
  • Glossary.

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

How to turn your technical product content into sales content

Customers are in constant search for information that will help them to effectively solve their problems. The first place clients usually go for this information is on the Internet. As a product or service company, you should always aim to produce high-quality content that can convert these prospects into loyal customers.

Your content needs to be of high quality, consistent, be easy to read, be pleasing to look at, be on-brand and on-voice. Technical content should always be accurate. As a sales tool, it needs to be technically, grammatically, semantically, and visually accurate.

It needs to be easy to find. It also needs to be easily searchable within. Your reader should be able to use a search engine to locate your public content quickly. And that same reader needs to be able to search for specific topics of interest within the content just as quickly and easily.

When should you hire a freelance writer?

According to HubSpot, 60% of businesses use content marketing strategies to gain and retain their customers. Creating, publishing and ultimately sharing content requires a lot of work. If you are experiencing any of these three things, then you should definitely use freelance writers:

  • Lack of enough time- It is tough running a business. This is because you have to constantly be on top of every sector in your company. Sometimes it is difficult to find time to create high-quality content. Hiring a content writer will boost your sales in two ways. One, the content produced will convert prospects to clients. And two, you will have more time to focus on other projects in your business.
  • If you are not able to produce enough technical content – If your company produces content frequently, then you know how stressful it is to always look for new content to post. You need to produce sufficient content that will convert prospects into long-term clients. Researching, creating, and publishing new content can be very overwhelming. The best option is to hire a freelance writer who can relieve you from that daunting task.
  • If you lack technical writing skills- Let’s face it; good writing is not that simple. Not everyone can produce the kind of writing that can capture the interest of an audience.
    There are numerous types of content. These include blog posts, white papers, web content, videos, social content, infographics, and presentations. To convey a message that is well understood by clients requires mastery of these skills.

How Technical Product Content Results in a Sales Content

  1. It has been estimated that 60 to 90 percent of buyers decide whether or not they will buy your product after reading the content on your website. They spend time evaluating different options from different companies. If your content is not engaging enough, they will simply move on to the next content from another company. It is your job to ensure you covert prospect clients to loyal customers. You can only do this by ensuring your technical product content has useful, relevant and engaging information. This will, in turn, increase your sales.
  2. You will gain loyal customers who understand your products or services. A happy client is a loyal client. To keep your clients happy, you need to provide useful information that will help them solve the problems they are facing.
  3. It saves you money. There are a lot of cases where clients sue a company for giving them wrong information about a product. This cases can cost a company a huge sum of money. In order to avoid falling victim of this predicaments, you should use the services of a technical content expert who will clearly convey the details of your products.

If you want your business to thrive, you have to keep in mind that all content is a pre-sale content. It is much easier to turn a prospect into a loyal customer if you provide them with high-quality content that is both informative and engaging.

How to create great quality content

Content writing is not rocket science although there is a method to it. The idea is to create something of interest that continues to attract attention. The attention you are seeking is not only from website visitors but also from search engines. The more often the search engines devour your content, the higher your pages will rank. The higher your pages rank, the more often they will appear in search results which in turn generates the traffic you want to your website.

Sounds pretty easy, doesn’t it? That is if you follow these simple guidelines to creating good quality content that attracts search engines and eventually humans to your website.

1 – Keep It Relevant

Probably the most important factor that will impact how the search engines see, understand and index your website pages is related to relevance. You need to keep the topics aligned with the purpose of the website. For example, if your website is for selling sports memorabilia, your content better be related to sports, collectibles and similar topics. Writing about anything else is going to hurt the way in which search engines will rank your website. If your website is about fishing or outdoor adventures, the content has to be about fishing or outdoor adventures. Writing about movies and food may not fit into the theme of your website. That is unless the movies and food can somehow be connected to fishing and outdoor adventures. Did you understand that?

2 – Keep It Regular

Posting one article a year is not going to be very helpful in attracting new and regular customers to your website. Sure, the ones who have already read your annual blog post may come back but the search engines may not. Search engines perform best when they get a steady diet of new content. This does not mean you are obligated to write a new and engaging article each hour or every day. You can get away with a slightly slower pace. Weekly or monthly at the very least will keep website visitors and search engines coming back.

3 – Keep It Real

Where a lot of web entrepreneurs miss the boat on quality content is by concentrating on technical writing as opposed to personal writing. You want your customers to feel as if you are their friend. When your content writing is honest and personal, it builds trust within the community that follows your website and business. There is far too much copy ‘n’ pasting going on these days and the websites that keep it real are the ones that will be the most successful. Share things with your customers and they will love you for it.

4 – Keep It Flowing

Something that tends to be forgotten in the ongoing game of SEO is that you need to also write content that is not specifically for search engines. In other words, you also need to write like a human for humans. What this means is several different things. Your content needs to flow seamlessly from one part of your website to another. It has to appear to fit in anywhere and have a consistent tone. You can use your content to tell a story to your readers and each new post can be viewed as a continuation of that storyline.

5 – Keep It Useful

One more important factor that should be considered when composing your quality content is to always, always, always make it something of use to the readers. It can be something as simple as a lesson-based post on how you learned to do something that relates to your business but also gives readers a takeaway that they may be able to use themselves. You can spend all your time on technical writing but if your website visitors are seeking some helpful tips or advice, you may not be serving them well without targeting their needs.

How else do you produce quality content?

The simple tips listed here should give you the foundation you need to construct some killer web content. Remember, you are not writing to win awards. You are writing to get the attention of search engines and website visitors. Once they start to understand the regularity of the relevant content you keep publishing on your website, you will see changes taking place. Your website visitor count will slowly increase. And, isn’t that the whole point of creating good quality content?

Troubleshooting Grammar Problems in Technical Writing

1. Sentence fragments

Make sure each word group you have punctuated as a sentence contains a grammatically complete and independent thought that can stand alone as an acceptable sentence.

Incorrect

Tests of the Shroud of Turin have produced some curious findings. For example, the pollen of forty-eight plants native to Europe and the Middle East.

[2nd sentence = fragment]

Correct

Tests of the Shroud of Turin have produced some curious findings. For example, the cloth contains the pollen of forty-eight plants native to Europe and the Middle East.

2. Faulty parallelism

Be sure you use grammatically equal sentence elements to express two or more matching ideas or items in a series.

Incorrect

The candidate’s goals include winning the election, a national health program, and the educational system.

Correct

The candidate’s goals include winning the election, enacting a national health program, and improving the educational system.

Incorrect

Some critics are not so much opposed to capital punishment as postponing it for so long.

Correct

Some critics are not so much opposed to capital punishment as they are to postponing it for so long.

3. Noun strings

The bulk of government and technical writing uses too many noun strings, or groups of nouns “sandwiched” together. Readability suffers when three words that are ordinarily separate nouns follow in succession.

Noun string: NASA continues to work on the International Space Station astronaut living-quarters module development project.

Correction: NASA is still developing the module that will provide living quarters for the astronauts aboard the International Space Station.

4. Subject-Verb agreement

The subject-verb pair guarantees that the sentence means something. Without this core, a sentence fragments and loses its power to speak. Indeed, a sentence only becomes complete when it contains at least a subject and a verb. Subjects and verbs must also agree with one another. That is, the form of the verb has to match the number of things in the subject. A singular subject takes a singular verb, while a plural subject takes a plural verb.

Incorrect: The two best things about the party was the food and the music.

Correct: The two best things about the party were the food and the music.

5. Misplaced Or Dangling Modifier
A misplaced modifier is a word, phrase, or clause that is improperly separated from the word it modifies or describes. Sentences with this error can sound awkward, ridiculous, or confusing. A dangling modifier is a word or phrase that modifies a word not clearly stated in the sentence.

Incorrect: After finally setting off on the trail, the morning felt more exciting.

Correct: After finally setting off on the trail, he felt the morning was more exciting.

6. Run-On Sentence
A run-on sentence occurs when you connect two main clauses with no punctuation.

Incorrect: She tried to sneak out of the house her mother saw her leaving.

Correct: She tried to sneak out of the house, but her mother saw her leaving.

Incorrect: He ran through the field as fast as he could all the while rain was soaking him to the bone.

Correct: He ran through the field as fast as he could. All the while rain was soaking him to the bone.

7. Lack Of Parallel Structure
Faulty parallelism occurs when two or more parts of a sentence are similar in meaning but not parallel (or grammatically similar) in form. It often occurs with paired constructions and items in a series.

Incorrect: The key directives of his boss were clear:

  • Meet monthly sales quotas.
  • Aggressive marketing techniques.
  • Reporting in every day.

Correct: The key directives of his boss were clear:

  • Meet monthly sales goals.
  • Practice aggressive marketing techniques.
  • Report in every day.

8. Split Infinitives
An infinitive is the word “to” with a verb. A split infinitive separates the word “to” and the verb with another word (often an adverb). There are no grammar rules that prohibit split infinitives, but many experts disapprove of them. If the sentence sounds awkward by correcting the split, our rule of thumb is to go with what makes the most sense in the context of your writing and for the ease of reading.

Incorrect: He wanted to gradually improve his strength by increasing the weight.

Correct: He wanted to improve his strength gradually by increasing the weight.

The Craft of Copywriting

Copywriting is like a magnet – it attracts audience towards your business. It has the power to persuade and influence. 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 works. 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.

Visit www.ThomasEcafe.com, or Email info@ThomasEcafe.com, or call +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?

In the vast majority of IT companies, software engineers spend a considerable amount of time in creating documentation such as user manual, operations manual, or administrative guide. When it comes to professional services team, they create different sets of documents like UAT, architecture document, customer requirement document, design document, and SOPs.

Due to spending a large amount of time in creating customer-facing documentation, It inhibits the engineers from spending quality time doing coding.  While the writing is certainly not a pleasant experience for engineers, inadvertently it gets reflected in the documentation and readers can discern it easily. This is where freelance writers play an active role by doing the documentation and letting the engineers focus on the development. If planned properly, most of the product/project documentation can be handled by a freelance writer.  As long as the company can meet certain commitments, the documentation can be done offsite.

  • An SME who can spare some time to interact with the writer
  • The application be accessible from the writer’s laptop
  • A demo of the application by an SME
  • Access to the design documents, functional specification, etc.
Where to look for a freelance writer

This is the best site to look for a writer. We have a pool of technical writers, copywriters, editors, and designers dedicated for your projects. There are other sites 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 information experience. We will assign quality writers, with relevant degrees and experience for your project.

What are the freelancing rates

The rates vary depending on the effort and duration of the work. A typical one-month technical writing project will cost from 3000 to 5000 SGD. On an hourly basis, it cost 25 SGD per hour. A copywriting project costs 50 SGD for a 500-words article.

For more details, visit www.ThomasEcafe.com, email info@ThomasEcafe.com, or call +65-82086393 to discuss.

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, provide information that guides readers in their use of tools and procedures. In other words, helping readers not just in using 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