Readability and Text Metrics in Technical Writing  

 

Contents 
Introduction 5 
Metrics in Technical Writing 6 
Why Metrics Are Important in Tech Writing 7 
Top Metrics for Tech Writing Teams 7 
Conclusion 9 
Metrics in Technical Writing (Part 2) 10 
Using Google Analytics for Online Documentation 11 
Conclusion 13 
Top 5 Text Metrics to Consider for User Documentation 14 
Terms and Neologisms 14 
Word Length 15 
Sentence Length 16 
Paragraph Division 17 
Grammar Constructions 18 
Conclusion 18 
How to Measure the Effectiveness of the Documentation 19 
Use Web Analytics 20 
Use Surveys and Interviews 21 
Do Usability Tests 22 
Analyze Support Tickets and Use Forums 23 
Conclusion 24 
How to Review Technical Documentation 25
Key Documentation Review Stages 26 
Conclusion 28 
ClickHelp as a Solution 29 
Easy Review Process with ClickHelp 29
ToDo Lists 30 
Review Comments 32 

 
2  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Workflow Improvements 35 

Conclusion 36 
Readability and Text Metrics 36
Text Metrics 40 
Readability Metrics 40 
Item Count Metrics 41 
General Metrics 42 
Other Ideas on Improving Your Documentation 42 
Conclusion 45 
   

 
3  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

 
 

Join Our Happy Customers  

 
4  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Introduction 
The  main  goal  of  a  technical  writer  is  to  create  user-friendly 
documentation.  In  order  to  do  this,  you should figure out the level of 
knowledge  of  your  target  audience  on  the  subject  in  question. When 
creating  documentation  for  professionals,  you  need  to  really  go 
in-depth.  If  you  are  writing  for  novice  users,  make  sure  to  cover  all 
the  key  moments  and  leave  out more complicated stuff that a novice 
reader  won't  need  and  will  just  find  confusing.  But  how  to  be  sure 
that  your  documentation  will  be  clear  for your target audience? Here 
is where readability and text metrics step in. 
 
In  this  ebook1,  we  will  tell  you  what  metrics exist nowadays, how you 
can  use  them  in  your  technical  writing  process,  describe  top  text 
metrics to consider for user documentation and many more.  
 
Of  course,  metrics  are  a  great  source  of  high-quality  content. Here is 
where  another  question  arises  -  how  to  get  them  and  understand 
which  one  you  need?  ClickHelp  makes  everything  to  ease  tech 
writers’  life,  so  readability  and  text  metrics  are  available  in  our  tool  - 
you  can  create  documentation  and  check  its  readability  level 
instantly  in  one  help  authoring  tool.  Keep  reading  to  learn  more 
about how it’s implemented in ClickHelp!

1
​Disclaimer:​ This e-book is designed for information purposes only. The publisher and the author(s)
is not engaged to render any type of psychological, legal, or any other kind of professional advice.
The content of each article is the sole expression and opinion of its author(s) and publisher. No
warranties or guarantees are expressed or implied with this e-book. Neither the publisher nor the
individual author(s) shall be liable for any physical, psychological, emotional, financial, or commercial
issues, including, but not limited to, special, incidental, consequential or other issues. You are
responsible for your own choices, actions, and results that might arise due to the use or misuse of this
e-book.
 
5  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Metrics in Technical Writing 

 
Metrics  are  the  easiest  way  for  managers  to analyze work processes, 
make  conclusions  and  see  whether  everything  is  going  according  to 
plan.  If  it  is  not,  some  changes  need  to  take  place.  Metrics  also  help 
controlling  employee  performance  and  efficiency  of  the  current 
processes. 
 
Technical  writing  requires  metrics  just  like  any  part  of  product 
development.  We  are  going  to  provide  you  with  insights  on  how  to 
implement  different  metrics  in  your  documentation  writing  process 
and explain how to make metrics work for your benefit. Metrics often 
end  up  being  some  annoying  thing  that  kind  of  has  to  be  done,  but 
no one ever sees any real positive effects. 
 
 
 

 
6  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Why Metrics Are Important in Tech Writing 

 
When  you  work  in  support,  it  is  quite  clear  what  can  be  measured. 
The  number  of  cases  answered/resolved,  how  many  messages  it 
takes  on  average  to  resolve  a  case,  levels  of  customer  satisfaction  - 
these  are  all  quite  obvious  metrics  by  improving  which  you  can 
change things for the better. 
 
As  for  a  tech  writing  team,  it  is  not  so  obvious  what  should  be 
measured.  If  we try measuring word count, for example, it can hardly 
take  us  anywhere  in  terms  of  documentation  quality.  Should  tech 
writers  measure  anything  at  all?  Yes.  And,  we  will  try  to  explain  our 
point  further.  The  first  instant  effect  one  gets  from  measuring 
something  is  the  focus.  If you need to report about your work results 
to  your  manager  by  the  end  of  the  week, you’ll have no choice but to 
work  on  your  metrics. This means that figuring out the right things to 
measure is very important. So, let's delve into this. 
 
Top Metrics for Tech Writing Teams 
 
Customer  satisfaction  is  a  complex  concept,  really.  A  nicely 
developed  product  is  just  one  piece  of  the  puzzle.  Tech  support  and 
user  manuals  contribute  to  customer  satisfaction,  as  well.  To 
measure  how  happy  customers  are  with  your  technical 
documentation,  you can use a rating system for help topics and, also, 
enable  commenting  for your ​online documentation portal​. Reviewing 
this  data  will  help  you  improve  the  weakest  help  articles,  and  raise 
case deflection​. 
 
Measuring  the  number  of  finished  topics  per person per a set period 
of  time  helps  project  managers  control  performance  efficiency.  One 
can  argue  that  some  help  topics  are  way  more  complicated  than 
others  and  require  in-depth  research,  so,  how  can  you  compare 
these  things?  It  is  true,  but  this  can  be  solved  by  making  these 
periods  longer,  for  example,  because  the average topic length will be 
 
7  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

more  or  less  the  same  on  a  bigger  scale  for  team  members  with  a 
similar role. 
 
For  project  managers,  having  all  statistics  like  drafts,  topics  under 
review,  finished  topics  on  one  screen  can  help  a  lot  with  time 
estimation  and  further  planning.  Help  authoring  tools  like  ​ClickHelp 
provide  such  statistics  out-of-the-box  alongside  with  many  options 
for  filtering  this  data  (by  status, by owner, by assignee, by date). Your 
can  check  out  data  for  any  particular  project  or  the  whole 
documentation  portal. And, here’s more - in ClickHelp, you can create 
custom filters for your specific needs using Filter Builder: 
 

 
 
Thanks to this, managing big projects can become easier. 
 

 
 
 
 
 
 
8  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Conclusion 
 
Analyzing  metrics  can  be  a  real  waste  of  time  when  there's  no  solid 
purpose behind this. First, one should define the goals, and then look 
for  the  right  means,  never  vice  versa.  Modern  online  documentation 
tools  for  technical  writers  can  provide  you  with  the  latter,  just  make 
sure  that  your  goals  are  set  correctly,  and  the  positive  change  will 
happen. 

   

 
9  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Metrics in Technical Writing (Part 2) 

 
 
Technical  writing  requires  tools  for  measurement  and  analysis  like 
any  other  work  process.  Although,  it  is  quite  difficult  to  decide  what 
metrics to use considering specifics of this field. 
We  began  discussing  this  topic  a  while  ago  and  figured  out  the  main 
aims  of  using  metrics  -  you  can  either  measure  a  documentation 
team’s productivity or the quality of your final product.  
 
Here,  we  are  going to look into the second aspect - how to assess the 
quality  of  the  final  output  with  Google  Analytics,  one  of  the  most 
powerful  tools  out  there.  And,  more  importantly, what to do with the 
retrieved data. 
 
 
 
 

 
10  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Using Google Analytics for Online Documentation 

 
Google  Analytics  is  a  free  tool  by  Google  that  offers  an  impressive 
amount  of  settings  and  options  to  get  all  the  essential  metrics  a 
website  owner  would  ask  for.  The  same way it will work for an online 
documentation portal. 
 

 
What  metrics  can  potentially  interest  a  technical  writer?  First  and 
foremost  -  the  amount  of  views  per  page.  This  is  how  you  can  see 
what  questions  bother  your  users  the  most.  Or,  e.g.  you  can  check 
how  much  time  a  person  spends  on  a  page  on  average.  Let’s  talk 
about  these  metrics  and  their  interpretations  in  detail.  We  advise 
using  this  information  when  making  changes  to  your ​documentation 
plan​. 

● Allocate  more  resources  to  work  with  the  most  viewed  help 
topics. This should be your primary concern. 
● Find  areas  of  expansion  for  your  documentation  project.  You 
might  want  to  add  new  topics  and  get  into  more  detail  about 
the functionality that users find more interesting or challenging. 
● Combine  Google  Analytics  with other approaches. For example, 
adding  the  feature  of  rating or commenting topics can help you 
get  the  right  idea  about  what  should be done with a topic. Your 
red  flags  are  high  views  and  low  rating/negative  comments. 
Re-work these topics first. 
● Help  topics  with  just  a  few  views  can  be  put  on  hold  for  now in 
terms of upgrade and revision. 

 
11  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

● Pay  attention  to  the  time  users  spend  reading  your  topics.  If 
you  notice  that  user stay on some topic pages for too long, look 
into  them  when  you  have  time  -  these  topics  might  be  too 
complicated  and  require  restructuring  or  adding  more  visuals 
for easier understanding. 
● With  Google  Analytics,  you  can  track  how  users  get  to  various 
pages  and  make  the  corresponding  changes  in  topics 
navigation to direct users. 
● Identifying  the  target  audience  has  always  been  important  in 
technical writing. With modern UX trends, this is becoming even 
more  significant.  Google  Analytics  can  help  with  that  -  you  can 
learn the geolocation, age, interests of your readers. 
● Tracking  bounce  rate  can,  again,  point  to  certain  topics  that 
require  special  attention.  Consider  this  -  a  topic  has  high 
bounce  rate  and  a  lot  of  views.  This  is  a  direct  sign  that 
something  is  off.  Most  probably,  people  expect  to  see 
something different in this topic. 
● For  those  of  you  who  have  paid  traffic  campaigns,  checking 
traffic  sources  is  also  important.  This  data  can  tell  you  a  lot 
about your campaign’s efficiency. 
● You  can  use  Google  Analytics  as  your  A/B  testing  platform. 
Technical  documentation  intersects  with  UX in many ways now, 
so A/B testing is gaining popularity among tech writers. 

With  that  said,  you  can  see  that  the  free  version  of  Google  Analytics 
offers  a  lot,  and  we  only  mentioned  the  most  obvious  ways  to 
measure  your  online  user  manuals’  quality. Once you get your hands 
on  this  app,  play  around  with  it,  try  different  things  - you might get a 
lot of use out of it. 
 

 
12  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

 
 
ClickHelp  ​online  documentation  tool  was  created  with  all  these 
potential  bonuses  in mind, so we added Google Analytics integration, 
and  configuring  it  is  just  a  breeze!  Three  clicks,  and  you  can  start 
working with this freemium web analytics service. 
 
Conclusion 
 
You  can’t  really  improve  anything  without  thorough  analysis.  Luckily, 
such  free  tools  like  Google  Analytics  can  provide  you  with  a  lot  of 
metrics  that  can  be  used  to  improve  your  technical  documentation. 
Don’t  expect  to  see  some  immediate  results  from  using  the  metrics, 
though.  It  will  require  time  for  you  to  try  out  different  metrics,  see 
which  are  working  for  you,  adjust  them.  The  best  result  will  be 
increased  customer  satisfaction  that  means  you  have  done  your 
work right. 
 
 
 
 
 
 
 
 
 
 

 
13  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Top  5  Text  Metrics  to  Consider  for  User 

Documentation 
 

 
 
We have been mentioning readability in this book quite a lot recently. 
No  wonder,  with  modern  trends  like  ​UX  writing​,  this  has  become  a 
real point of concern for many technical writing teams. 
 
Luckily,  readability  is  not  that  abstract,  it  can  actually  be  broken 
down  into  pretty  specific  elements.  Here,  we  are  going  to  talk  about 
five  text  metrics  that  need  to  be  considered  for  creating  better  user 
manuals that can be understood easier. 
 
Terms and Neologisms 

Technical  documentation  is  prone  to  contain  too  many  terms, 

newly-coined  words  and  abbreviations.  This  can hinder readers from 

 
14  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

full  understanding  of  the  text. Besides, this is one of the reasons why 

users  don’t  like  technical  documentation  -  interpreting  all  the 
unknown words and concepts takes too much time. 
 
Terms  and  ​neologisms  in  user  manuals  can  hardly  be  avoided,  as 
technical  documentation  is  based  on  very  specific  fields  and  subject 
matters.  But,  there  are  some  ways  to  make  it  easier  for  all  the 
unprepared readers. 
 
All  terms  and  new  words  should  be  explained in simple language. To 
help  readers  deal  with  difficult  words  in  online  documentation,  you 
can: 

● create links and cross-references inside user manuals 

● add hidden parts of text with in-depth explanations 
● create web help bubbles 
● make up a g ​ lossary​ for reference 

Word Length 
 
It  is  quite  clear  that  shorter  words  are  easier  to  understand.  If  we 
also  consider  that  on  average  1  in  10  people  has  some  degree  of 
dyslexia  that,  among  other  things,  can  cause  issues  with  reading, 
word length starts to matter even more. 
 
There  are  two  interconnected  concepts  here  -  length  and  frequency 
of  use.  Historically,  they  are  kind  of  related.  And,  no  wonder,  we  are 
sure  that  most  of  you  would  rather  choose  the  word  “start”  than 
“embarkation”  which  are  synonymous  in  certain  contexts.  So,  in 
practice,  this  means  that  technical  writers  should  control  the  length 
and  frequency  of the words they use - any restrictions are impossible 
here,  of  course,  but,  in  general,  to  create  nicer  user  manuals,  one 
should  start  looking  for  more  simple  synonyms  to  awkward  lengthy 
words. 
 

 
15  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Sentence Length 
  
Here’s  another  metric  related  to  length  - sentence length. The rule of 
thumb  is  one  sentence  -  one  idea.  However,  some  notions  are  hard 
to  explain  in  one  sentence,  and  that  is  alright,  we’ll  talk  about 
paragraph division further, too. 
 

 
 
For  readability  purposes,  sentence  length  should  be  around  20 
words,  while  some  scientific  papers  and  documents  contain 
sentences  with  60+  words.  What  is  quite  interesting,  in  literature, 
some  writers  manipulate  sentence  length  consciously,  to  increase 
readers’  attention.  Short  sentences  are  intertwined with long ones to 
create  a  “rhythm”,  where  the  shorter  ones  grab  your  attention  and 
the longer ones help to hold it. 
 
In  technical  writing,  sentence  length  should  help  deliver  a  message 
clearly.  So,  our  general advice is to try making sentences with around 

 
16  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

20  words  your  default  option.  If  you  can squeeze your idea into even 

fewer words without losing its clarity - great, go with that. 

 
Paragraph Division 
 
Even  Leonardo  da  Vinci,  ​the  greatest  technical  illustrator  took 
advantage  of  paragraph  division.  Trully,  paragraphs  can  help  a 
reader get through the most complex help topic. 
 

 
 
Basically,  each  paragraph  should  present  and  support  one  theme. 
This  ensures  that  a  reader  can  look  through  a  text  and  get  the  main 

 
17  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

thoughts  without  reading  the  text  thoroughly.  Plus,  getting 

information  in  chunks  simply  feels  more  comfortable  and  gives  a 
breather to our brain to process it bit by bit. 
 
So,  don’t  underestimate  paragraphs  and  make  sure  that  they 
constitute the backbone of your help topics. 
 
Grammar Constructions 
 
Sentences  should  be not only relatively short but also simple, as well. 
For  example,  abusing  passive  constructions  can  make  your  text  feel 
much heavier. Active voice is more preferable. 
 
It  is  difficult  to  say  why  people  tend  to  use  passive  a  lot,  maybe 
because  it  adds  some  scientific  feel  and  seriousness  to  writing… But, 
that’s a common misconception that technical documentation should 
be  all  sciency.  On  the  contrary,  technical  communicators  have  been 
trying  for  a  while  now  to  make  user  manuals  lighter  and  more 
appealing.  And,  getting  rid  of  complicated  grammar  constructions  is 
a sure way to do so. 
 
Conclusion 
 
The  text  is  the  core  of  technical  writing.  It  can  be  viewed  from  many 
angles:  grammar,  style,  logic,  punctuation,  readability,  even  its  looks 
in  terms  of  font  and  color.  All  components  are  important  here,  so, 
this  post  is  meant to cover at least some small part of all the possible 
approaches. 

 
18  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

How  to  Measure  the  Effectiveness  of  the 

Documentation 

 
 
Technical  writing  and  communication  involves  communicating 
complex  information  to  specific  audiences  with  clarity  and  accuracy. 
The  key  word  here  is  communication,  which  is  a  term  for  two-way 
interactions.  But  in  case  of  technical  writing,  the  addressee  side  is 
shrouded in mystery.  
 
Technical  writers  often  have  a  very vague idea of the end-users, their 
level  of  competence  and  their  needs,  because  they  lack  knowledge 
and  feedback  from  their  audience.  But  a  clear  understanding  of  the 
target  audience  knowledge  is  essential  for  adjusting  the  writing  for 
the  needs  of  the  particular  audience  and  communicating  the 
message in the proper manner. 
 

 
19  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

In  this  part,  we’ll  focus  on ways to gather metrics that may further be 

used  for  improving  the  quality  of  the  documentation  and  level  of 
user satisfaction. 
 

 
 
Use Web Analytics 
 
Web  analytics  is  a  powerful  instrument  that  allows  measuring  the 
user  experience.  You  may  use  Google  Analytics,  Adobe  Analytics,  or 
some  other  web  analytics  service,  to  collect  the  most  basic  but  still 
useful  information  about  your  target  audience.  It’ll  provide  you  with 
the following metrics: 

● Time spent on a particular page. 

● The number of viewed pages per visit. 
● The number of page visits, and more. 

 
 
 
 
 
 
 
 
 
 
 

 
20  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

For  example,  ClickHelp  technical  writing  tool  has  ​built-in  statistics 

feature  that  allows  monitoring  the  viewing  statistics  of  a  particular 
topic or the whole project. 

 
Using  metrics  of  web  analytics  you  can  make  certain  conclusions  on 
how  to  adjust  the  documentation  and  make  it  suit  your  audience’s 
need.  For  example,  you  may  learn  which  topics  are  the  most  viewed 
and  how  much  time  users spend on these pages. So in case a topic is 
popular  but  users  spend  too  much  time  there,  enough  to  read  it 
several  times,  this  may  mean  that  this  topic  needs  to  be  improved: 
you may want to rewrite it using ​plain language​, add ​screenshots ​and 
gifs, use less ​jargon​, make it more clear and concise and so on. 
 
Use Surveys and Interviews 

Another  way  to  learn  more  about  the  shortcomings  of  the  user 
documentation  is  to  directly  ask  the  end-users  if  they  had  a  positive 
experience  with  a  particular  piece  of  documentation.  In  order  to  do 
that,  you  need  a  built-in  feedback  mechanism  on  every  help  topic 
page of the documentation. 
 
 
 

 
21  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

 
 
We  advise  you  to  use  a  simple  response  mechanism  like  thumb-up 
and  thumb-down  buttons.  For  example,  ClickHelp  contains  ​ratings 
report  feature  that  gathers  statistics  according  to  the  data  of  the 
following widget. 
 

 
More  detailed  insights  can  be  gathered through fill-in forms that pop 
up  when  users  punch  the  thumb-down  button.  This  way  you  may 
learn  more  about  whether  a  particular  topic  met  users’  needs.  You 
may  also  use  a  pop-up  with  a  short  interview  that  appears  when 
users are attempting to leave the page. 
 
Do Usability Tests 
 
Unfortunately,  only  a  small  percentage  of  users  usually  provide 
feedback  and  even  less  leave  their  comments  in  case  of  negative 
experience.  It  means  that  conclusions  based  on  the  surveys  are  not 
always representative. So option #3 is to do a usability testing. 
 
According  to  ​Jakob  Nielsen​,  you  only  need  5  random  participants  to 
conduct  a  usability  study  and  receive  reliable  results.  In  order  to 
gather  even  more  representative  statistics,  you  need  to  find  five 
participants  representing  different  types  of  documentation  users: 

 
22  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

developers,  new  users,  novice  users,  expert  users  and  so  on 
depending on the type of the documented product. 
 
Instead  of  gathering  lots  of  participants  for  one  study,  try  doing 
several  usability  tests  with  a  small  number  of  participants.  A  variety 
of  tests  conducted  with  a  small  group  of  people  proves  much  more 
useful  than  doing  one  study  with  a  large number of people. This way 
you’re  going  to  gather  more  data  and  feedback  and your company is 
going to achieve more for the same amount of money invested. 
 
Analyze Support Tickets and Use Forums 

Another  way to measure whether the documentation is effective is to 
research  support  tickets  and  forum  threads.  Unfortunately,  neither 
of  these  sources  is  informative  and  reliable  enough  to  make  it  the 
primary source of user feedback. 
 
Users  contacting support usually don’t describe their experience with 
the  documentation:  whether  they  consulted  the  docs,  what  they 
were  looking  for  and  whether  they’ve  found  the  solution.  But  when 
they  do,  it  allows  you  to  find  out  if  a  particular  topic  contains  all  the 
necessary  information  about  the  subject  matter  or  it  should  be 
expanded. If the topic contains the necessary solution, but the user is 
unable  to  find  it,  then  you  need  to  consider  improving  the  particular 
topic or the whole structure of the documentation. 
 
When  analyzing  the  information  from  the  support  tickets  and  user 
forums,  you  need  to  keep  in  mind  that  these  sources  of  user 
feedback  provide  a  one-sided  picture.  When  users  are  satisfied  with 
their  experience  with  the  docs  they  do  not  contact  the support team 
or share their experience on the forums. 
 
 
 
 
 
23  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Conclusion 

Unlike  other  types  of  writing,  technical  writing  communicates  with 

different  types  of  audience  that  depends  on  the  documented 
product,  its  functionality,  the  peculiarities  of  the  niche  it  belongs  to. 
Web  metrics,  surveys,  interviews,  usability  tests,  support  tickets,  and 
user  forums  together  provide  a  set  of metrics, that allows measuring 
the  effectiveness  of  technical documentation and its particular topics 
and  sections.  Quantitative  and  qualitative  analysis  of  the  mentioned 
sources  allows you to find opportunities to improve the quality of the 
docs and the level of user satisfaction. 
 
   

 
24  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

How to Review Technical Documentation 

Now  let's  talk  about  reviewing  technical  documentation.  This  topic  is 
discussed  in  the  ​techcomm  community  a  lot  since  it  is  the 
cornerstone of a good help writing workflow. 
 
Before  analyzing  approaches  to  reviewing,  we  would  like  to  draw 
your  attention  to  the  fact  that  having  a  convenient  environment 
tailored  to  reviewers’  needs  is  the  first  step  you  should  take  to 
improve  the  review  process.  So,  it  all  starts  with  the technical writing 
software  you  are  using.  Make  sure  it  allows  setting  up  an  effective 
process. 
 
Sending  files  for  review  via  email  is  an  obsolete  workflow  that  often 
causes  confusion  and  some  technical  documents  can  even  be  lost 
along  the  way.  Luckily,  modern  help  authoring  tools  are here to save 
the  day.  For  example,  ClickHelp  has  a  special  reviewer  role available, 

 
25  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

this  feature  alone  can  bring  quick  improvements.  But  there's  more: 
in  ClickHelp,  you  can  instantly  add  and  manage  review  notes  and 
to-do  lists.  We  recently  enhanced  this  functionality  as  part  of  the 
ClickHelp A​ urora Polaris update​. 

 
Key Documentation Review Stages
 
Tom  Johnson  from  Idratherbewriting  singles  out  five  review  stages 
on his​ ​blog​: 

● Review with the doc team 

● Review with the product team 
● Review with the field engineers and support group 
● Review with legal 
● Review with beta partners 

If  content  goes  through  these  five  stages  it  should  be  stripped  of  all 
major  bugs  for  sure.  Each  stage  has  a  different  team  responsible  for 
content  review  and  they  all  are  essentially  looking  for  issues  in 
different  areas.  This  way,  technical  writers  can  get  maximum 
coverage.  The  overlapping  areas  do  not  feel  like  a  waste  of  time 
either, on the contrary, this just means more thorough checking. 
 
We  overall  agree  with  Tom's  approach,  however,  we  would  like  to 
shift  focus  a  little  towards  post-publishing  stages  of  a  technical 
documentation lifecycle. 
 
The  idea  that  before  user  manuals  are  published,  they  should  be  as 
bug-free  and  precise  as  possible  seems  legit.  Nevertheless,  in  ​agile 

 
26  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

software  development  things  need  to  be  happening  fast,  which  can 
lead  to  quality  loss.  Let's  not  forget  about  the  fact  that  a 
documentation  team's  workload  heavily  depends  on  devs  and  QA. 
So,  short  notice  changes  in  documentation  plans  are  something  one 
needs to be prepared for. 
 

 
 
When  technical  documentation  is  published,  things  get  real  as  your 
clients  become  your  reviewers.  To  succeed  at  this  stage,  make  sure 
to  follow  up  on  every  issue  reported  by  the  clients  as  soon  as 
possible.  Another  critical  aspect  of  this  process  would  be  effective 
collaboration  with  the  support  team.  Support  team  members 
reference  technical  documents  all  the  time,  and  they  are  the  first  to 
receive  user  complaints,  as  well.  So,  this  cross-team  communication 
channel  needs  to  be  open  and  allow  quick  back-and-forth  data 
exchange. 
 
 
 

 
27  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

 
Conclusion 

A  smooth  and  robust  review  process  is  critical  for  technical  writing 
teams  as  the  content  quality  depends on it directly. Every team has a 
unique  review  process  that  meets  their  requirements.  Hopefully, 
with  this  article,  we  made  this  complicated  topic  a  bit  simpler  and 
you will be able to use some tricks in your workflow. 
   

 
28  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

ClickHelp as a Solution 

 
Now,  let’s  see  how  it’s  implemented  in  ClickHelp  and  how it can ease 
your technical writing process. 

Easy Review Process with ClickHelp 

 
Reviewing  is  a  crucial  part  of  technical  writing. And, with this thought 
in  mind,  the  ClickHelp  team  did  their  best  to  make  this  feature  even 
better in the March product update. 
 
Reviewers  bring  a  fresh  perspective  to  your  help  topics  and  show 
ways  of fixing and improving them. When a technical writer finishes a 
help  topic,  you  probably  wouldn't  call  it  a  complete  fixer-upper,  it  is 
still  in  progress  for  a reviewer. Read further to find out how easy and 
intuitive reviewing has become in our online documentation tool. 

 
29  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

ToDo Lists 
 
When  you  see  a  green  square  with  a  number  next  to  a  topic  title  in 
the  TOC,  this  means  that  some  ToDo  items  exist  for  this topic. There 
is  also  an  email  notification,  but,  we  believe  that  adding  such  an 
indication  directly  to  the  TOC  makes  it  so  much  easier  to  track  the 
progress. 
 
The number in the green square displays how many unfinished items 
are left for the topic: 

 
Should  you  open  the  topic  and  click  'TODO’  at  the  top  of  the  page, 
you  will  see  the  ‘Topic  ToDo  List’  panel  in the left part of your screen. 
Such  lists  usually  include  some  things  you  need  to  add  or  change  in 
the topic in question: 

 
30  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

 
As  you  can  see  in  the  screenshot  above,  two  items  are  marked  as 
done,  so,  the  ​technical  writer  working  on  this  help  topic  needs  to  fix 
just  one  last  thing,  mark  the  item  as  done,  and  the  document  will be 
ready for another review iteration. 
 
For  your  convenience,  if  a  child  topic has unresolved ToDo items, the 
parent gets a green circle next to it in the TOC: 

 
31  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

ToDo  lists  are  often  used  to  make  up  a  plan  for  a  new  topic,  as  well, 
so no details will go missing. 

Review Comments
 
One  of  the  most  demanded  features  gets  an  update  in  the  new 
ClickHelp  release  -  we  have  drastically  improved  in-text  review 
comments. 
 
When  a  review  comment  is  added,  an  email  notification  is  sent.  It 
includes  explicit  information  about  the  comment.  Email  notifications 
are also sent when review comments are deleted or resolved. 
 
To  check  if  a  topic  has  some  unresolved  comments,  look  for  orange 
squares  with  numbers  next  to  topic  titles  in  the  TOC.  These 
indicators work just like the ones for ToDo lists. 

 
On  a  reviewer's  part,  things  are  as  simple  as  this:  a  reviewer  selects 
some  text  they  have  comments  for,  and,  on  the  'Review’  tab,  they 
need to click 'Add Comment’. 

 
32  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

 
As  soon  as  the  comment  is  submitted,  the  text  requiring  correction 
will be marked with yellow in the topic. 

 
To  see  the  comment,  just  click  the  text  and  a  popup  with  the 
comment will appear. 

 
33  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

 
Now,  you  can  reply  to  the  comment,  mark  it  as  resolved  or  delete  it. 
The corresponding notifications will be sent to the topic owner. 
 
You  can  see  the  whole  list  of  review  comments  by  clicking  the 
corresponding  button  in  the  header  -  you  don't  need  to  go  into  the 
editing mode for that. 

 
 
 
 
 
 
 
 
 

 
34  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

 
This is how a list of comments looks: 

 
Another  great  improvement  is  the  fact  that  you  can  now  share  links 
to  review  comment.  This  feature  makes  the  workflow  smooth  and 
swift. 
 
Also,  we've  made  it  possible  for  you  to  see  all  resolved/deleted 
comments.  By  default,  they  are  hidden  on  the  comment  list  but  can 
be turned on. 
 
The  latest  release  opens  up  the  possibility  of  tracking  Project 
Readiness  by  review  comments.  The  ​ClickHelp  users  will  be  able  to 
see  how  many  unresolved  review  comments  are  left  to  work  on  for 
projects, topics, authors and reviewers on a single screen. 

Workflow Improvements 
 
We  have  implemented  a  couple  of  new  features  enhancing  the 
review  workflow.  One  of  the  most  prominent  improvements  here  is 

 
35  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

the  ability  to  change  the  topic  owner/assignee  without  ​unlocking  the 
topic​.  Plus,  since  the  March  ClickHelp  release,  you  will  be  able  to  do 
that for several topics at the same time. 
 
But  there's  more  -  email  notifications  can  now  be  configured  on  the 
profile  level!  This  provides  more  customization  options  so  the 
workflow can be shaped for each user individually. 

Conclusion 
 
We  have  been  listening  carefully  to  our  clients,  taking  notes  all  the 
way  to  deliver  these  functionality  updates.  The  review  process  has 
become  much  more  visual  and  easier  to  use.  With  the  new  updated 
process  we  have  rolled  out,  you  can  ​start  creating  better  user 
manuals right now​! 

Readability and Text Metrics 

 
You  sure  have  a  general idea about how readable your user manuals 
are.  But,  does  this  idea  have  any  real  scientific  proof?  Well, ClickHelp 
is  going  to  help  you  with  that  via  our  new  awesome  readability 
formulae available since the March product update. 
 
We  have  developed  a  precise  and  intricate  mechanism  to  evaluate 
the  readability  of  your  technical  documentation  using  various 
metrics.  Analyzing  some  metrics  gives  you  a  shortcut  to 
understanding  your  readers  better  and  adjusting your team's writing 
style  to  their  needs  while  others  allow  gaining  more  control  over the 
team's efficiency. 
 
The  new  metrics  that have become available in ClickHelp allow a very 
deep and detailed analysis of text. 
 
 

 
36  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

You can find some of them right at the top of the WYSIWYG editor: 

 
Even  Time  to  read  and Readability (FRES) alone can instantly give you 
an idea of what the topic in question is like. 
 
The  ClickHelp  team  added  dozens  of  useful  metrics  you  can  analyze. 
You  can  select  to  display  any  metric  at the top of the page by clicking 
the cog wheel icon and selecting the one you need. 

 
The  new  metrics  are  grouped  into:  Text  Metrics,  General,  Readability 
and Item Count. 
 
37  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

You can examine all of the metrics on one screen: 

 
Readability  metrics  are  calculated  with  many  factors  in  mind. 
ClickHelp  analyzes  text  on  different  levels  to  provide  you  with  a 
score. 
 
Let's  take  Flesch  Reading  Ease  and  Flesch-Kincaid  Grade  Level  as  an 
example;  these  particular  readability  indexes  are  tied  to  the 
American  school  grades  system.  Basically,  when  you  get  a  certain 
score,  you  will  understand  what  hypothetical  background  a  reader 
needs to have to easily read this topic. 
 
When  analyzing  topics  based  on  different  indexes,  pay  special 
attention  to  the  extremes.  If  all  your  topics  are  getting  pretty  much 
the  same  score  within  one  metric,  everything  is  fine.  But,  if  you 
stumble  upon  topics  with  unusually high or low scores, double-check 
them, something must be off. 
 
Comparing  scores  of  different  technical  writers  is  another  way  to 
benefit  from  readability metrics. If some team members keep getting 
 
38  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

lower  scores,  they  might  have  poor  writing  habits,  like,  their 
sentences  tend  to  be  too long or they contain too many terms. When 
you  possess  this  knowledge you can turn this situation around pretty 
quickly. 

It  goes  without  saying  that  more  readable  text  equals  shorter 
sentences,  more  lightweight  grammatical  structures,  and  frequently 
used  words.  Now,  all  this  is  trackable  and  visible  with  the  Text 
Metrics​. 
 
Tracking  employees’  performance  via  Text  Metrics  is  also  possible. 
For example, you can figure out how many words a technical writer is 
supposed  to  write  in  a  week  and  check  how  all  team  members  are 
doing  as  far  as  the  word  count  is  concerned.  Of  course,  this 
approach  cannot  guarantee  high  proximity,  but  conclusions  can 
definitely be made based on it. 
 
ClickHelp  provides  authors  and  reviewers  with  a  great  number  of 
metrics  that  will  help  your  team  create  readable  documentation. 
Here  is  a  list  with  descriptions  of  all  the  metrics  that  you  can  use  for 
your projects and topics. 
 
 
 
 
 
 

 
39  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Text Metrics 
Here  are  text  metrics  which  are  available  in  ClickHelp  and  you  can 
use for managing your writing process: 

● Words​. The number of words in a topic.  

● Characters​. The number of characters in a topic.  
● Characters  (without  spaces)​.  The  number  of  characters 
without spaces in a topic.  
● Sentences​. The number of sentences in a topic. 
● Syllables​. The number of syllables in a topic. 
● Unique  text  (words,  %  of  total)​. The number of unique words 
in a topic.  
● Printed  pages  (A4  size)​.  The  approximate  number  of  printed 
pages  the  current  topic  text  will  occupy  when  printed  on paper 
of the A4 size. 
● Printed  pages  (Letter  size)​.  The  approximate  number  of 
printed  pages  the  current  topic  text  will  occupy  when  printed 
on paper of the Letter size. 
● Average  words  per  sentence​.  The  average  number  of  words 
per sentence. 
● Average  syllables  per  sentence​.  The  average  number  of 
syllables per sentence.  
● Average  characters  per  sentence​.  The  average  number  of 
characters per sentence.  
● Average  syllables  per  word​.  The  average  number  of  syllables 
per word.  
● Average  characters  per  word​.  The  average  number  of 
characters per word.  

Readability Metrics 

A  readability  score  is  a  computer-calculated  index  which  can  tell  you 

what  level  of  education  a  reader  will  need  to  understand  a  text 
easily.  Readability  really  matters  because  technical  writers  should 

 
40  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

write  documentation  that  users  will  understand  and  gladly  keep 

reading.  Moreover,  search  engines  like  Google  also  care.  Google  has 
even  publicly  stated  that  readability  is  one  of  the  factors  in  its 
ranking  algorithm.  So,  the  readability  score  also  helps  you  improve 
SEO. 

That's  why  ClickHelp  provides  you  with  a  number  of  readability 

metrics.  For  example,  Flesch  Reading  Ease,  Gunning  Fog  Index,  New 
Dale-Chall  Formula  and  so  on.  This  will  make  your  documentation 
more  effective.  In  this  section,  you  will  find  the  details  of  all  those 
metrics  calculation  and  meaning,  so  you  can  read  about  them  in 
detail: 

● Time to Read Metric 

● Flesch Reading Ease 
● Flesch-Kincaid Grade Level 
● Gunning Fog Index 
● Coleman-Liau Index 
● Automated Readability Index 
● SMOG Index 
● Linsear Write 
● New Dale-Chall Score 
● FORCAST Grade 
● Average Grade 

Item Count Metrics 

Here are item count metrics that you can examine for your topic: 

● Images​. The number of images in the topic. 

● Links​.  The  number  of  links  in  the  topic.  All  links  are  counted  - 
cross-topic  links,  File  Storage  links,  external  web  links,  mailto 
links. 
● Tables​. The number of tables in the topic.  
● Videos​. The number of videos in the topic.  

 
41  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

● Snippets​. The number of snippets in the topic.  

● Variables​. The number of variables in the topic.  
● Conditional  include  blocks.  The  number  of  conditional  blocks 
of the I​ nclude​ type in the topic.  
● Conditional  exclude  blocks​.  The  number  of  conditional  block 
of the E ​ xclude​ type in the topic.   
● Resolved  review  comments​.  The  number  of  resolved  review 
comments.   
● Deleted  review  comments​.  The  number  of  deleted  review 
comments.  

General Metrics 

The  ​General  ​category  includes  just  one  metric  at  this  time:  the  date 
and  time  of  the  latest  topic  update.  If  you  select  this  metric,  it'll 
display only the date.  

Other Ideas on Improving Your Documentation 

How  else  can  you  identify  which  articles  are  well-performing  and 
which  ones  need  adjustments  or  updates?  With  ClickHelp,  it's  easy. 
The  online  documentation  tool  provides  users  with  various  reports 

 
42  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

which  you  can  examine  to  improve  your  documentation.  Here  is 
what you can use to improve your writing: 

● As  we  mentioned above, you can examine the ​Topics Views and 

Ratings  Report​.  When  readers  visit  your  publication  the  following 
widget appears, so every reader’s reaction is gathered in the report. 

 
● Monitor  the  number  of  unique  users  who  visited  your 
documentation  for  a  specific  period  of  time.  This  information  can  be 
generated  for  the  entire  online  documentation  portal,  or  just  be 
specific  for  a  user  manual  or  every  topic  thanks  to  ClickHelp  ​Reader 
Count Report​. 

As  for  Restricted  Manuals,  the  details  table  will  give  information  on 
which  specific  ​Power  Readers  viewed  your  documentation.  Studying 
 
43  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

such  statistics  can  be  extremely  useful  in  long  term  planning.  One 
way  to  apply  it  is  to  see  which  help  topics  get  more  views  and  treat 
them  with  more  attention  -  these  topics  need  to  be  updated  timely 
and constantly improved and elaborated. 

● Analyze  the  ​Search  Queries  Report  that  allows  you  to  monitor 
the  keywords  queried  by  readers.  You  can  sort  the  results  by  last 
queries  to  learn  what  and  when  readers  search  for  the  particular 
keyword. 

 
● Use  ​Google  Analytics​.  It  is  one  of  the  top  freemium  marketing 
tools  for  tracking  and  reporting  website  traffic.  Google  Analytics  can 
be  integrated  right  into  a  ClickHelp  portal.  So,  you  can  examine  a 
huge variety of possible metrics like: 
○ Visitors - its the number of people who visited your portal. 
○ Content  -  Google  Analytics  allows  evaluating  which  help  topics 
are the most popular once.  
○ Average  Time  Spent  on  a  Page  -  this  metric  will  show  you  how 
much time readers spend on any topic on average. 
○ Navigation paths, and much more. 

 
44  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

Conclusion 
Surely,  one  of  the  main  goals  of technical writing is to get your target 
audience.  And  text  and  readability  metrics  can  be  a  solution  in  this 
situation.  However,  you  should  keep  in mind that there is no good or 
bad  score.  It  depends  on  what  result  you  want  to  achieve.  For 
example,  if  your  target  audience  is  wide,  the  score  should  be  lower 
than  if  you’re  aimed  the  B2B  audience.  Nevertheless,  your  writing 
should  be  clear  and  concise,  so  people  will  get  the  main  idea  quickly 
and keep reading your documentation gladly. 
 
This  is  possible  in  ClickHelp  that  allows  technical  writers to write and 
examine  instantly  whether  their  content  is  appropriate  or  not.  You 
can  try  our  text  and  readability  engine  yourself,  just  order  a  ​free 
30-day trial​. 
 
For  more  stories  for  technical  writers,  web  developers  and  web 
designers  willing  to  grow  ​subscribe  to  our  blog  and  follow  us  on 
Facebook​, ​Twitter​, ​Medium​, ​Telegram​, ​LinkedIn​. 
 
Other free ebooks which you may find useful: 
 
● Responsive Layouts: Getting Started Guide 
● HTML Templates for User Manuals 
● Technical Writer Career Guide 
● Types of Technical Documentation 
 
Good Luck with your technical writing! 
ClickHelp Team   

 
45  Share this book:  
 

Readability and Text Metrics in Technical Writing  

 

 
46  Share this book: