Writing effective content

Short guide to writing simple yet effective content

Content

Should you read it

If you are… Student

writing college report

Developer writing client documentation

Blogger writing some

blog

Should you read it

And, you ever fe lt…

Confused on what to write

Angry that you cant find

better words

Frustrated after reading

your own content

Scolded by boss/teacher for

poor writing

Should you read it

In summary, read it if you are

Trying to write some technical content

You are not a professional writer

You are just starting with technical writing

You struggle to find better words

Should you read it

Do not read if…

Looking for content strategy guide

You are trying to write a story/fiction

You are very experienced writer

Trying to find software tool for writing

What is technical content

Content

Blog post

An article explaining technology

Product documentation

Project understanding report

Requirement specification

Product review

Tutorial for training

API documentation

Project report for college

And so much more…

How it differs

Technical vs. Non technical

Technical topic demands simplicity

Non technical demands mystery

Contents in Technical

writing can be connected or disconnected

Technical writing needs to be objective i.e. free from

personal emotions

Technical writing needs to be very

precise, accurate & unambiguous

Where things go wrong

I made few very wrong

decis ions

Indecisiveness in content theme

Imperfect content abstraction

Assumption about readers

Breaking up basic principles of

simple and effective writing

Content organization

Ambiguous writing style

Unreadable content

Content theme

Every techn ica l wr ite-up has “one ”

under ly ing message, po int or concept .

Th is concept is “content theme ” .

If there i s no under ly i ng

theme , t hen content i s

use less . Don ’ t pub l i s h i t .

But , what i f t here i s

more than one theme for

s i ng le wr i te -up?

Content theme

Resu lt i s loud

exp los ion of

content for the

user .

Content theme

Intended original theme: Explaining idea of microprocessor to

non-technical people

What was in the article: Author compared microprocessor with

microcontroller. For that he first

explained what microcontroller is

followed by elaborate comparison.

Real world example: Article about basics of microprocessors

Outcome

Content theme

Final outcome • Very lengthy monolithic article

• On scanning, it create illusion about

central idea of article. Is it about

microprocessor, microcontroller or

comparison between the two?

• Too much for the user to digest

• Reading this content becomes heavy

burden for user

Needs improvement

Content theme

Key principle:Each wr i te -up or

content shou ld have

exact ly one and on ly

one centra l t heme .

In previous example:

• Remove microcontroller section

• If required, split the article into

two parts with new title for

second article

Content abstraction

“Content abstraction ” is the

process of selecting important

information whi le ignoring

unnecessary minute detai ls .

Give users what ’ s

rea l l y necessary &

important .

If user doesn ’ t need

someth i ng , j u st om i t

i t f rom the content .

Content abstraction

Intended original theme: Explaining the new features and

performance of Intel core i7 processor

Sample paragraph: Next slide shows sample paragraph

from the article and try to determine if

there is anything that can be removed

or simplified.

Real world example: Product review of Intel core i7

Intended audience: Buyer interested in buying new processor

Content abstraction

Intel Core i7 is a series of several families of desktop and laptop

processor built using Nehalem, Sandy bridge and Ivy bridge

microarchitectures. Latest Ivy bridge processors are based on 22nm

technology that makes use of 3D transistors producing less heat and

ultimately resulting in better power consumption. Intel Core i7 includes

support for PCIE 3.0 and can play 4000p i.e. 4K resolution videos. Being

a multithreaded processor, i7 in total provides 8 threads (2 threads per

core) for operating system. It supports L3 cache of 3MB. The processor

comes with triple channel memory architecture resulting in faster

processing of instruction.

Outcome

Content abstraction

Content analysis – (possible confusion to potential reader)

• Is i7 a single processor or there are multiple processors?

– If multiple, which one should I buy?

– Are desktop and laptop processors are different?

• What is Nehalem, Sandy bridge and Ivy bridge?

• What are 3D transistors? Do I really need to care for this?

• What is 4K video?

– Can’t I play my regular HD videos?

• I thought i7 is multicore but it says it is multithreaded. Am I really

looking for this processor?

• What it means triple channel? Do I need at least 3 RAM in system?

Content abstraction

• Does common average buyer really need to know all this jargon

about processor?

– Does processor nanotechnology matter to him?

– Is he a power user to know difference between triple channel and dual channel?

– Should a bank accountant know difference between thread and core?

• Wait a min,

– What about graphics card support?

– Where is the mention of user’s favorite clock speed?

• The article is accurate, precise but may be ideal for hardcore

computer professional & not for average reader…

Leve l of abstract i on i s

dependent on type of readers

Content abstraction

Intel Core i7 is a new computer processor by Intel built on latest

technologies which makes it one of the fastest processors available in

the market. It includes support for latest graphics cards enabling you to

play extreme games and run heavy software applications. With core i7,

along with regular HD videos, it is now possible to play ultra high

quality HD videos offering you the finest movie experience. Intel has

incorporated many technologies advances in the processors that

ultimately leads to reduced heat generation and power consumption.

In terms of specification, it comes with 3.2 GHz of clock speed with 3MB

of cache.

ImprovedAbstracted

unnecessary

th i ngs

Content abstraction

Key principle:Abstract the content

to i nc l ude most

important concepts .

Ignore everyth i ng e l se .

Remember :Le ve l o f ab s t rac t i o n i s

dec i d ed by t h e t ype o f

r eader s o f t h e con ten t .

Reader stereotypes

Understanding the readers

before writ ing content &

categoriz ing them is cal led as

stereotyping reader .

Fi rst step to

wr i t i ng a good

content i s study

o f readers &

the i r behav i or .

Reader stereotypes

Software requirement specification (SRS)

Development team

Quality control team

Management team

Will be read by…

Software requirement specification (SRS)

SRS must specify

requirements

SRS should specify

estimation matrix

SRS should specify business

use cases

Reader stereotypes

Product review article

Prospective buyers

read by…

Tutorial on some subject

Students

read by…

Product documentation

Product users

read by…

API documentation

End developers

read by…

Reader stereotypes

The end result is…

Your readers (audience) should dictate your content

Reader stereotypes

In case of tutorials or series of articles on a

particular topic, readers can be classified as

Readers that prefer

continuity in all articles so

that they can understand

how whole piece work

together

Reader that prefer each

article as disjoint so that

they can read any article

in any sequence as time

permits

Then choose the approach that is more

apt to explain the technology/topic

Reader stereotypes

Key principle:Your readers shou ld

d i ctate your content .

Remember :Stereo t yp i n g r eader i s

t h e ve r y f i r s t s t ep i n

w r i t i n g go od con ten t .

Basic writing principles

Clarity

Accuracy

Precision

Rationale

Emotionlessness


Content clarity

“Jack and Jill decided to

party. He took cola and

he had coffee.

Content is true

but c lar ity is

absent . Who took

what?


Content accuracy

“Two players are playing

game of Tennis.

Content is c lear

but accuracy is

quest ionable .


Content precision

“Panda is a very heavy

and slow animal.

Content is clear, accurate

but not precise. How heavy

is Panda? Is it bigger than

dinosaur?


Content rationale

“They met. They fell in

love. He proposed her.

But they did not marry.

Content is clear, but

there is no rational

justification to why

they did not marry.


Content detachment (emotionlessness)

“I think landline phone is

better than mobile phones.

Unless writing

personal experience,

avoid any personal

opinion which may be

biased.


Key principle:Fo l low bas i c pr i nc ip l es

o f good wr i t i ng .

Remember :Ru l e s a re made to be

b ro ken . I f yo u h a ve a

good r eason to go

aga i n s t s ome p r i n c i p l e ,

f e e l f r ee to b r eak i t .


• You cannot write an article in a single sitting of few hours

• Creative content demands

– You think and think over again

– You need to keep searching for inspiration everywhere

– You research thoroughly on the topic of your writing

• Keep smartphones, notepads handy for taking notes

– Humans tend to forgets things easily

– Creative thoughts come unexpectedly in mind out of nowhere


“Content organization ” is the

art of keeping your thoughts,

workplace managed and easi ly

searchable.

It i s not the actua l organ i zat i on o f

content body i t se l f . It ’ s about your own i n ventory o f i deas .

The art o f

management o f

content body i s

actua l l y “content

h i e rarchy ” .


Monkeys do such

th ings . You are not

one , are you?


Humans keep

th ings organ ized .

Drop by drop makes an

ocean. When you keep things

organized and take note of all

those small thoughts that

pops up in mind randomly,

you tend to create bigger

picture more coherent,

rational and apt.


Key principle:Keep your workspace

and ideas organ i zed .

Remember :Organ i z i n g i s o ne o f t h e

mos t d i f f i c u l t t h i n g to

master . Peop l e s t udy MBA

f o r t h e sa ke o f

o r gan i z i n g . Ha ve pat i e nce .

It w i l l t a ke t ime . B u t ,

r eward w i l l b e wo r t h y .

Unambiguous writing

I never said she stole my money.

What mean ing

does th is

sentence

convey?

Unambiguous writing

I never said she stole

my money.

1

I d id not say i t , somebody

e l se sa id she sto le my money .

Unambiguous writing


my money.

2

I sa id lots o f t h i ngs , but I

d id not say th i s t h i ng .

Unambiguous writing


my money.

3

I d id not say i t , I imp l i ed

( i nd i rect ly ) i t .

Unambiguous writing


my money.

4

She d id not stea l i t . It was

somebody e l se who d id i t .

Unambiguous writing

I never said she stolemy money.

5

She d id not stea l my money ,

I l ent or gave i t to her .

Unambiguous writing


my money.

6

The money that she sto le was

not m ine . It was somebody

e l se ’ s money .

Unambiguous writing


my money.

7

She sto le someth i ng e l se f rom

me , but not money .

Unambiguous writing

• How you write and structure sentences can have very

large impact on readability

• Try to keeps statements as simple as possible

– Simplicity has amazing power

• Each content should have exactly one theme

– All writing should echo towards that one theme

• It goes beyond writing to any form of communication

Unambiguous writing

Key principle:Stay away f rom any

sort o f amb igu i t y .

Embrace s imp l i c i t y .

Remember :When i n do ub t o ve r

mean i n g , d o n ’ t p u t i t

t h e re . Th i n k o f s omet h i n g

e l s e .

Readable content

• Content readability is about “presentation”

– Readability has nothing to do with actual content

• Very important especially on digital medium like web

– Users tend to read slower on screen devices (mobiles, desktops)

– With books or magazine, users read word by word but for web

most of them scan jumping and hoping from anchor to anchors

– Users switch immediately if they cannot read easily as web

provides many alternatives

Readable content

So, what's a readable content?

Content is “readable ” i f reader

can understand the underly ing

theme of the content without

actual ly reading it .

On web , most w i l l

“scan ” f or i n format i on

& not read i t .

Readable content

Taj MahalThe Taj Mahal is a white marble mausoleum located in Agra, Uttar Pradesh, India. It was built by Mughal emperor Shah Jahan in

memory of his third wife, Mumtaz Mahal. The Taj Mahal is widely recognized as "the jewel of Muslim art in India and one of the

universally admired masterpieces of the world's heritage".

Taj Mahal is regarded by many as the finest example of Mughal architecture, a style that combines elements from Islamic, Persian,

Ottoman Turkish and Indian architectural styles.

In 1983, the Taj Mahal became a UNESCO World Heritage Site. While the white domed marble mausoleum is the most familiar

component of the Taj Mahal, it is actually an integrated complex of structures. The construction began around 1632 and was

completed around 1653, employing thousands of artisans and craftsmen.The construction of the Taj Mahal was entrusted to a board

of architects under imperial supervision, including Abd ul-Karim Ma'mur Khan, Makramat Khan, and Ustad Ahmad Lahauri.

Lahauri is generally considered to be the principal designer.

Is it easily readable?

Readable content

Taj Mahal

The Taj Mahal is a white marble mausoleum located in Agra, Uttar Pradesh, India. It was built by Mughal emperor Shah Jahan in

memory of his third wife, Mumtaz Mahal. The Taj Mahal is widely recognized as "the jewel of Muslim art in India and one of the

universally admired masterpieces of the world's heritage".

Taj Mahal is regarded by many as the finest example of Mughal architecture, a style that combines elements from Islamic, Persian,

Ottoman Turkish and Indian architectural styles.

In 1983, the Taj Mahal became a UNESCO World Heritage Site. While the white domed marble mausoleum is the most familiar

component of the Taj Mahal, it is actually an integrated complex of structures. The construction began around 1632 and was

completed around 1653, employing thousands of artisans and craftsmen.The construction of the Taj Mahal was entrusted to a

board of architects under imperial supervision, including Abd ul-Karim Ma'mur Khan, Makramat Khan, and Ustad Ahmad Lahauri.

Lahauri is generally considered to be the principal designer.

Is it better?

Readable content

From the freeway, take the second exit for Pepper Lake which you reach by

following the road for approximately three miles. Just before you reach Pepper

Lake itself, take the small road to your right next to the Tourist Information

building. Follow the road for approximately two miles until you come to a fork,

take the left hand fork and drive for another 400 yards until you reach the

clearing where the wedding ceremony will take place. See you on Saturday!

From the freeway, take the second exit for Pepper Lake which you reach by

following the road for approximately three miles. Just before you reach Pepper

Lake itself, take the small road to your right next to the Tourist Information

building.

Readable content

From the

freeway, take

the second

exit for Pepper

Lake which

you reach by

following the

road for

approximately

three miles.

Just before

you reach

Pepper Lake

itself, take the

small road to

your right next

to the Tourist

Information

building.

Follow the

road for

approximately

two miles until

you come to a

fork, take the

left hand fork

and drive for

another 400

yards until you

reach the

clearing where

the wedding

ceremony will

take place. See

you on

Saturday!

From the

freeway, take

the second

exit for Pepper

Lake which

you reach by

following the

road for

approximately

three miles.

Just before

you reach

Pepper Lake

itself, take the

small road to

your right next

to the Tourist

Information

building.

Which one is readable? This or next?

Readable content

From the freeway, take

the second exit for

Pepper Lake which you

reach by following the

road for approximately

three miles. Just before

you reach Pepper Lake

itself, take the small road

to your right next to the

Tourist Information

building. Follow the road

for approximately two

miles until you come to

a fork, take the left hand

fork and drive for

another 400 yards until

you reach the clearing

where the wedding

ceremony will take place.

See you on Saturday!

From the freeway, take

the second exit for

Pepper Lake which you

reach by following the

road for approximately

three miles. Just before

you reach Pepper Lake

itself, take the small road

to your right next to the

Tourist Information

building.

Is it better than previous?

Readable content

• Readability is about typography

– Line height

– Font selection

– Font size and weights

• Readability is about visual design

– Use of images as visual aids

– Highlighting important keywords

– Use of bullets, lists rather than paragraphs

Readable content

Key principle:Make sure the theme

o f content can be

understood by mere

scann i ng o f text .

Remember :Learn l i t t l e b i t abo u t

t ypograph i c p r i n c i p l e s

and bas i c s o f v i s u a l

de s i g n .

Other stuff

This part looks too

complex. Can you please

try to simplify it?

Tip:Get your

content

rev i ewed f rom

peers or

f r i ends . It

he lps e l im i nate

common s i l l y

m i stakes that

are not so

apparent .

Other stuff

Tip:Rev i ew your content

many t imes be fore

gett i ng i t pub l i s hed .

Remove anyth i ng

that i s doubt f u l .

Keep your content

c lean and f ree f rom

language errors .

Other stuff

Tip:He lp other peop le i n

gett i ng the i r

content r i g ht . You

w i l l l earn many new

th i ngs . And , others

w i l l he lp when you

w i l l need i t .

Other stuff

Tip:Time pressure , worst

enemy o f wr i ter ,

often k i l l s creat i v i t y .

But rea l i t y i s a lways

t ime bound . Learn

e f fect i ve t ime

management and

keep check on your

t ime .

Finally ask yourself

Before you publish:

Does your content answer what,

why and how questions?

Does your content convey exactly

one message?

Have you done research about your

readers?

Is your content clear, simple,

accurate, precise & unambiguous?

If no then rethink…

Harshal Patil

@softHarsh

http://definitelysimple.com

http://www.linkedin.com/in/hapatil

Author:

http://definitelysimple.com/

http://www.linkedin.com/in/hapatil

Technology

Writing effective content