13
Best Practices for Technical Writing By: Atinder Sodhi

Best practices in Technical Writing

Embed Size (px)

DESCRIPTION

Best practices in Technical Writing by Atinder Sodhi in the TWB Alumni knowledge sharing session.

Citation preview

Page 1: Best practices in Technical Writing

Best Practices for

Technical WritingBy: Atinder Sodhi

Page 2: Best practices in Technical Writing

Technical Writing in briefTechnical writing is writing on a specific subject for a specific purpose to a specific audience. Technical writers can be considered as a bridge between people who know technology and people who use it.They understand the complications of technology and put it in simple words that help the user understand and use the technology. User Manuals, Online help files, Reports, Proposals, Procedures, Release notes , Brochures, etc.

Page 3: Best practices in Technical Writing

Analyze the audience Audience analysis is most important consideration in planning, writing, and reviewing a document.

To write effective documentation that suits the users, we must understand their needs.

In other words, do not create a 300-page manual when a quick reference guide will do.

Page 4: Best practices in Technical Writing

Write reader-friendly documentation

Technical writing is full of complex information. Do not confuse readers with heavy information.

Write document to audience's readability level.

Document should help the readers to complete their required task.

Page 5: Best practices in Technical Writing

Use active voice Use active voice to ensure that your readers and users clearly understand your documentation.

It is commonly held that passive voice is acceptable in technical writing.

However, overuse of passive voice, or use of passive voice in long and complicated sentences, can cause readers to lose interest or to become confused.

Page 6: Best practices in Technical Writing

Use advance organizers In technical writing, an advance organizer is a bulleted list at the beginning of a chapter that provides an overview of the chapter.

The most important single factor influencing learning is what the learner already knows.

Advance organizers help users process and retain information based on what they already know.

Page 7: Best practices in Technical Writing

"Chunk" your documentation Break your documentation into smaller portions using bulleted lists, shorter paragraphs, and cross-references.

Chunk your documents according to topics—one topic per chunk.

Chunking keeps the readers' attention, providing them space to stop and absorb what they've read.

Page 8: Best practices in Technical Writing

Provide adequate white space Too much text crammed onto a page intimidates readers and turns them away.

In technical writing, always use white space around the text to break up pages.

Too much text can tire the eyes.

Page 9: Best practices in Technical Writing

Use cross-references to related information Use cross-references to link related information that is described elsewhere in the document. Cross references are not essential to the current discussion.

In online documentation, provide adequate hyperlinks to cross-reference related information.

Page 10: Best practices in Technical Writing

Use step/action tables Step/action tables provide a practical way to separate procedural steps from other descriptive information.

This is a very important aspect of information mapping.

Procedures contained in step/action tables are easy to read and follow, increasing document effectiveness.

Page 11: Best practices in Technical Writing

Create a quick reference chapter, section,or guide

A quick reference summarizes the most common user procedures, which is very helpful to users.

A quick reference help readers get started without having to comprehend a large amount of information beforehand.

Page 12: Best practices in Technical Writing

Create a glossary of terms.

Create comprehensive indexes.

Edit the documentation.

Page 13: Best practices in Technical Writing

[email protected]

THANK YOU

ANY QUIERIES?