SEO and Technical Writing  

 

Contents 
Introduction 4 
SEO Tips for Technical Writers 5 
Just Write 6 
Use Links 7 
Add Meta Tags 7 
Create Human-Readable URLs 8 
Minimize Page Load Time 9 
Conclusion 9 

Google Analytics in Technical Writing - What For? 10 

Moving Towards More Data Analysis 11 
Using Google Analytics in Technical Writing 12 
Conclusion 14 

Online Documentation and SEO 15 

Introduction 15 
Human-Readable URLs 15 
Crawler-Friendly Pages 16 
Keywords Meta Tag 17 
Google Analytics 18 
AJAX Navigation & Hashbang 19 
URL Changes During Navigation 19 
URLs for Web Crawlers 20 
Hashbang for Navigation 21 
Content Order 22 
Robots.txt 24 
Robots.txt and Online Documentation 25 
Lazy-Loading Images 26 
Improve Web Site Performance 26 
Handling Images - Typical Approaches 27 
Handling Images - The Recommended Approach 30 
Lazy-Loading Images - Full Sample Code 35 

Conclusion 37 

 
2  Share this book:  
 

SEO and Technical Writing  

 

 
Join Our Happy Customers 
  

 
3  Share this book:  
 

SEO and Technical Writing  

 

Introduction 
Nowadays,  technical  documentation  is  created  online  for  many 
reasons: 
 
● users can get access easily via any device; 
● content  is  more  user-friendly  -  you  can  add  videos,  gifs,  and 
interactive elements to help readers get the main idea fast; 
● online  documentation  tools  make  technical  writers  life  easier  - 
a  doc  team  can  write,  edit  and  design  documentation  from 
anywhere around the world; 
● your ​documentation can be used as a marketing tool​. 
 
In  this  ebook1,  we'll  talk  about  the  last  point  -  how  to  get  the  most 
SEO  effect  of  your online documentation as software documents and 
user  guides  don’t  only  help  convey  a  technical  writer's  ideas  to  an 
audience,  but  also  make  way  to  marketing  opportunities.  From  this 
ebook you’ll learn: 
 
● SEO tips for technical writers. 
● How to use Google Analytics in technical writing. 
● Tips  on  improving  your  online  documentation  to  make  it 
SEO-friendly. 

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.
 
4  Share this book:  
 

SEO and Technical Writing  

 

SEO Tips for Technical Writers 

 
Things  like  DevOps  and  Agile  create  more  opportunities  for 
cross-team  collaboration.  And,  that’s  what  is  required  of  any 
business  now  -  smoother  seamless  product  delivery.  Technical 
writers  are  a  huge  part  of this puzzle, and, finally, some real merge is 
happening  due  to  technical  documentation  being  available  online. 
The  same  rules  apply  to  online  docs  as  to  any  other  form  of  written 
content  on,  say,  your  corporate  website.  Meaning  that  the  ​SEO 
benefits documentation can bring should be taken seriously. 
 
Here  are  SEO  tips and lifehacks to help you discover the full potential 
of online user manuals in this regard. 

Just Write 
Well,  that  can’t  really  count  as  a  tip,  but,  it is important to emphasize 
that  as  soon  as  you  post  your  technical  documentation  online,  it 
starts  working  for  your  benefit  in  more  ways  than  one.  For  example, 
 
5  Share this book:  
 

SEO and Technical Writing  

 

if  you  are  using  ​ClickHelp  ​to  deliver  online  manuals,  you  can  rest 
assured  that  all  your  help  topics  are  indexed  by  Google  and  other 
major  search  engines.  What is documentation in terms of SEO? A pile 
of  the  best  keywords  you  can  find  for  a  product.  So,  when  indexed 
properly, a user manual becomes a real keyword generator. 

Use Links 

 
 
The way modern documentation works, you won’t even need to think 
about linking pages too much - you will be doing this by default. Links 
are  essential  for  user  manual  navigation,  so,  hopefully,  you  already 
have  a  nicely  woven  net  of  links  inside  your  ​online  documentation 
portal​.  Here’s  what’s  important,  though  -  you  can  and,  in  fact,  you 
should  add  external  links  to  your  technical  documentation.  Adding 
links  to  your  corporate  website,  for  example,  is  a  great  idea  that  can 
bring more traffic. 
 

 
6  Share this book:  
 

SEO and Technical Writing  

 

Add Meta Tags 

This  feature  is  available  for  all  ClickHelp  users  instantly.  The  title  tag 
would  be the most crucial on-page SEO factor in this section. The title 
tag  itself  is  what  search  engines  use  to  display  as  search  results.  But 
you  can  also  add  some  keywords  just  before  the  title  to  achieve  a 
stronger SEO effect. 
 
Another  useful  thing  is  a meta description. It can be assigned to each 
topic  individually,  and  search  engines  are  going  to  show  it  in  search 
results as a page description snippet. 
 
We  should  probably  also  mention  meta  keywords  here,  they  can  be 
added  on  the  ​help  topic  ​level  in  ClickHelp.  Unfortunately,  they  are 
disregarded  by  Google  at  the  moment,  but,  still,  if  you  are  working 
with  other  search  engines,  too,  and  you  know  that  they  are  paying 
attention  to  meta  keywords,  then  here’s  another  SEO  booster  for 
you. 

Create Human-Readable URLs 

Even  URLs  can  become  another powerful SEO tool. 'Human-readable 
URLs'  means  that  you  can  literally  read  them,  and  you  don’t  have  to 
be  a  robot  to  do  that.  Instead  of  random-looking  digits,  a 
human-readable URL can contain the name of a help topic. 
 
And,  this  also  improves  the  overall  usability  of  your  technical 
documents.  A  reader  will  know  for  sure  what  link  they  are  about  to 
open by just looking at its name. 
 
7  Share this book:  
 

SEO and Technical Writing  

 

Minimize Page Load Time 

 
Page  load  time  is  an  important  SEO  factor  taken  into  account  by 
search  engines.  In  general,  documentation  portals  are  more 
lightweight  than  edgy  and  complex  corporate  websites,  but  still, 
there  are  certain  risks  we  should  be  mindful  of.  Screenshots  and 
other  images  can  make  loading  your  user  manuals  significantly 
slower.  Don’t  forget  to  set  up  a  size limit for images and add them to 
your documentation plan or style guide. 
 
Try  avoiding  longer  help  topics.  This  will  give  you  the  best  of  both 
worlds,  really:  better  SEO  as  pages  load  faster  and  portioned 
easier-to-comprehend help topics. 

Conclusion 
You  can  definitely  combine  various  tools  to  get  great results for your 
business.  And,  we  hope  we’ve  proven  to  you  that  technical  writing 
can indeed be a great SEO tool. 
 
8  Share this book:  
 

SEO and Technical Writing  

 

Google Analytics in Technical Writing - What For? 

Google  Analytics  is  traditionally  an  ​SEO  and  marketing  tool.  These 
departments  are  known  to  take  advantage  of  this  product  daily  to 
track  multiple  data  and  come up with conclusions regarding whether 
their current strategy is any good. 

Technical  writers  have  their  own  stats  to  pay  attention  to.  They  are 
mostly  connected  with  internal  stuff,  everything  along  the  lines  of 
project management. But there's more to it. 

 
9  Share this book:  
 

SEO and Technical Writing  

 

Moving Towards More Data Analysis 

 
Doc  team  managers  are  paying  a  lot  of  attention  to  the  progress 
being  made  within  a  project,  and  what  individual  stats  of  the  team 
members  show.  Knowing  how  well  and  fast  this  or  that  ​technical 
writer  does  certain  types  of  job,  how  much  there  is  left  to  edit,  etc.  - 
things  like  that  help  project  managers  make  the  right  choice  when 
assigning  tasks  to  people.  Especially  if  we  are  talking  about  handling 
important and urgent stuff. 

By  the  way,  seems  like  artificial  intelligence  is  going  to  make  this 
particular  task  of  allocating resources much easier in the foreseeable 
future  -  technologies  are  being  tested  and  developed  that  learn 
behavior  patterns.  After  a  machine  gets  enough  data,  it  will  be  able 
to  distribute  tasks  automatically  among  team  members  based  on 
previous  choices,  so  all  routine  actions  might  be  automated  and 
won't require serious human participation. 

 
10  Share this book:  
 

SEO and Technical Writing  

 

Well,  there's  that.  But,  this  kind  of  statistical  data  is  but  a  small 
fraction  of  things  to  analyze  and  use  to  improve  technical 
documentation.  There's  a  different  approach  built  over  stats  related 
to end-users. And, Google Analytics is an awesome tool for that. 

Using Google Analytics in Technical Writing 

As  you  are  probably  aware,  GA  deals  with  external  data  as  opposed 
to the stats within a doc team we've mentioned earlier. In GA, you get 
to learn things like page views, time spent on a page, bounce rate. 

These  numbers  can  be  interpreted  and  used  for  long  term  planning 
as well as quick fixes. 

● Pay  attention  to the most visited ​help topics​. Make sure to keep 

them  up  to  date  on  a  first-priority  basis.  And,  always  look  for 
ways to improve them. 
● Look  at  your  bounce  rate  closely.  Long  topics  with  a  high 
bounce  rate  aren't  a  good  sign.  Revise  their  content  to  make 
sure  it  is  comprehensive  and  well-structured,  and  the  topics 
don't look like a wall of text that scare readers away. Also, check 
their titles - these can be misleading hence the bounce rate. 
● If  topics  are  rarely  visited,  that's  a  point for concern, too. Again, 
check  the  titles.  Or,  maybe,  these  topics  are  not  in  the  section 
they  are  supposed  to  be  in.  A  lot  of  help  topics  completely 
abandoned  by  readers  can  be  a  sign  of  poor  linkage  and  bad 
cross-topic navigation. 
● You  can  even  share  some  of  your  insights  with  devs  and 
product  owners.  Like,  for  example,  when  you  see  a  crazy 
number  of  visits  on  a  help  topic,  this can mean that the feature 

 
11  Share this book:  
 

SEO and Technical Writing  

 

described  there  is  far  from  being  intuitive  and  requires 

revisiting. 

That's  only  scratching  the  surface  of  ways  to  apply  Google  Analytics. 
But this is already a lot. 

Another  feature  that  adds  real  value  to  Google  Analytics  is  its  ability 
to  provide  an  overview  of  your  ​average  reader​.  That's  important  to 
know for sure. 

With  all  that  said,  remember,  technical  writers  don't  have  to  be  data 
gurus,  especially  around  such  concepts  like  a  target  audience  -  they 
can  (and,  in  fact,  they  should)  get  this  information  by  collaborating 
with  other  teams.  The  teams  that  have  a  more  profound 
understanding  of  your  target  audience,  such  as  the  marketing  team, 
for example. 

GA  creates  solid  grounds  for  team  collaboration  that  can  be  really 
beneficial  for  your  company  in  many  ways.  And,  it  is  not  just  about 
the  target  audience,  although  this  aspect  is  huge  on  its  own,  deeper 
 
12  Share this book:  
 

SEO and Technical Writing  

 

interpretation  of  any  GA  stats  can  be  learned from marketing or SEO 

departments and later adopted in documentation teams. 

Conclusion 

Quite  an  important  point  to  mention  -  Google  Analytics  has  free  and 
paid  versions.  As  a  technical  writer,  don't  even  think  about  buying 
the  paid  one.  First, it costs a ton of money, second, you won't be able 
to  dig  deep  enough  to  use  all  its  features.  It  was  made  with  serious 
analytical processes in mind, so let's leave it to the pros. 

The  free  version  of  Google  Analytics  is  over  and  above  what  you 
might  need  in  terms  of  stats.  Work  out  how  you  can  use  it  to  your 
advantage.   

 
13  Share this book:  
 

SEO and Technical Writing  

 

Online Documentation and SEO 

Here, we’ll talk about tips on improving your online documentation 
to help you make it SEO-friendly. 

Introduction 

Search  Engine  Optimization  (SEO)  has  always  been  something  only 

the  Marketing Teams thought of. What they did was creating relevant 
content,  putting  the  right  words  to the page content, linking pages to 
each  other,  and  so  on.  As  a  result,  with  the  right  content  on  your 
website,  search  engines  were  able  to  properly  understand  the 
context,  and  help people easier find your web site. And now, with the 
documentation  going  online,  technical  writers  got  the  same  SEO 
concept in their hands. 

With  online  documentation,  we  can  now  use  ​SEO  tools  and 
approaches  to  add  visibility  to  online  docs.  This  visibility,  in  its  turn, 
will  certainly  improve  your  products  and  company  visibility  on  the 
web.  This  works  because  the  online  documentation  articles  typically 
have  all  the  right  terms  and  good  cross-page  links.  At  that,  there  are 
several SEO-related techniques that improve the result even further. 

Human-Readable URLs 

The  words  put  to  URLs  of  web  pages  are  very  important  to  search 
engines  (as  we  mentioned  above).  In  certain  cases,  these  words  are 
more  important  than  the  page  contents.  If  you  don't  have  the  right 
terms  in  the  online  documentation  topic  URLs,  this  is  going  to  lower 
the  SEO  effect  significantly.  For  example,  this  can happen if you have 
only  numeric  identifiers  in the topic URLs, instead of meaningful text. 
Besides,  people will also be more comfortable clicking a link that says 
something more than just a numeric identifier. 

At  that,  to  give  a  help  topic  a  readable  URL,  you  don't  have  to  think 
much  -  most  topics have titles, which can be used as the basis for the 
URLs.  

 
14  Share this book:  
 

SEO and Technical Writing  

 

Crawler-Friendly Pages 

Web  crawlers  used  by  search  engines  request  web  pages  by  URL.  At 
that,  most  of  the  search  ​spiders  do  not  run  any  scripts  when 
loading pages... 

It's  like  when  you  disable  scripts  in  your  web  browser  and  browse 
pages.  If  some  pages  heavily  rely  on  scripts  to  render  their  contents, 
the  web  crawlers  may  get  incomplete  or  incorrect  page  contents. 
This makes your SEO efforts of very little value to the end result. 

This is what the architecture of a standard Web crawler looks like: 

This  does  not  mean  that  you  can't  use  scripts  in  your  online 
documentation.  Scripts  may  give  some  nice  functions  and  visual 
effects  to  the  help  topic  contents.  At  that,  it  certainly makes sense to 
have  a  script-free  version  of  those  pages  for  the  search  engines  to 
properly  index  the  contents.  In  ClickHelp,  we  have  put  the  needed 
attention  to  these  specifics  and  made  sure  the  web  crawlers  get  the 
topic  contents  properly.  So,  when  using  ClickHelp  to  create  ​online 
documentation​,  you  don't  need  to  bother  about  web  crawlers  not 
running scripts. 

Another  important  note  –  don’t  forget  about  ​metadata  with  the 

"robots"  name.  The  value  of  this  meta  tag  can  significantly  change 

 
15  Share this book:  
 

SEO and Technical Writing  

 

the  web  crawlers  behavior.  For  example,  ​<meta  name="googlebot" 

content="noindex"  />  prevents  the  page  from  being  indexed  by 
Google crawlers (read more at s​ upport.google.com​). 

Keywords Meta Tag 

First  of  all,  ​the  "keyword"  attribute  for  the  Meta  element  is 
designed  especially  for  Search  Engines.  For  example,  ​<meta 
name="keywords"  content="technical  writing  tool, documentation tool"/> 
informs  Search  Engines,  that  this  webpage  contains  information 
about  ​tools  for  technical  writing  and  documentation  authoring.  But 
most  SE  doesn’t  consider  it  nowadays.  In  particular,  Google  doesn’t 
consider it since September 2009. 

Another  purpose  of  the  meta  attribute  is  to  help  users  find  some 
materials  grouped  by  one  theme.  It  makes  navigation  easier.  In  this 
case,  keywords  are  automatically  displayed  on  some  block  on  a 
webpage. It’s the main purpose of keywords today. 

ClickHelp  provides  the  ​Index  Keywords  and  Taxonomy  feature  to 

help  you  organize  your  online  manual,  and  give  your  readers  an 
additional  navigation mechanism - the Index tab in the UI. Also, index 
keywords  and  taxonomies  can  be  used  to  fine-tune  full-text  search 
results and make it easier for readers to find relevant topics: 

 
16  Share this book:  
 

SEO and Technical Writing  

 

So,  when  setting  up  your  Keywords  for  a  help  topic,  you  are  getting 
two  good  things:  ​the  Index  tab  will  use  them  for  easier  navigation, 
and  ​the  ClickHelp  SEO  engine  will  use  them  for  the Keywords meta 
tag.  

Google Analytics 

SEO-specialists use Google Analytics to ​analyze statistics​: 

● traffic sources, including organic and paid search traffic sources 

● audience (demographics, behavior, etc) 
● EO (queries, landing pages, etc) 
● social statistics 
● content 
● conversions. 

Analytical  data  can  be  used  later  for  various  purposes  and  making 
decisions for future website optimization. 

Google  Analytics  separate  data  of  your website from other resources 

using  a  unique  identifier  –  ​the  Web  Property  ID​.  Google  Analytics 
Support:  "While you might think about your website or mobile app as 
a  distinct,  real-world  piece  of  property,  like  a  storefront,  Google 
Analytics  understands  a  property  only  as  a  resource  associated  with 
your  tracking  code.  When  you  track  a  resource  using  Google 
Analytics,  you  include  a  property  ID  in  the  tracking  code that you put 
on  your  web  pages  or  in  your  app  source  code.  Performance  data, 
like  the  number  of  visitors or screen views, for resources tagged with 
the same ID, is collected into the corresponding property." 

 
17  Share this book:  
 

SEO and Technical Writing  

 

You  can  find  the  Web  Property  ID  on  your  Google  Analytics  account 
homepage or in the Admin section: 

In  ClickHelp,  you  can  easily  connect  your  online  documentation  to 
your  Google  Analytics  account,  and  ​get  all  the  nice  statistical 
information free of charge​.  

AJAX Navigation & Hashbang 

When  readers  are  browsing  online  documentation,  they  click 

cross-topic  links  a  lot  and  use  the  Table  of  Contents  navigation quite 
often.  With  these  use  cases,  if  the  entire  page  reloads  on  every 
navigation, this may harm the documentation usability. 

To  improve  online  documentation  responsiveness,  technical  writers 

often  use  ​AJAX  navigation​.  The  idea  is  simple  -  link  clicks  are 
handled  by JavaScript, and only a part of the page reloads. It certainly 
helps  with  the  responsiveness  part!  However,  this  dynamic 
navigation may have a couple of side effects technical writers need to 
keep in mind, let’s take a look at them. 

URL Changes During Navigation 

In  simplest  implementations,  the  address  bar  of  the  browser  does 
not  change  during  AJAX  navigation.  New  content is programmatically 
put  on  the  page,  but  no  real  navigation  happens  in  terms of the web 
browser.  So,  if  you  want  to  link  to  a  specific  topic  of  such  online 
documentation,  and  you  just  copy  the  current  page  URL,  it  will 
probably point to some “home page” of the system. 

 
18  Share this book:  
 

SEO and Technical Writing  

 

An  easy  solution  would  be  changing  the  URL  from  JavaScript  when 
dynamic  navigation  happens.  However,  this  has  been  impossible 
until recently when browsers started to support HTML 5. 

To  resolve  the  inconvenience,  such  systems typically have something 

like  the  “Permanent  Link”  button  that  gives  you  a  URL  that  you  can 
use  to  access  the  current  page.  Another  solution  was  to  use  anchor 
tags  (​page.html#anchor1​)  -  it  is  possible  to  change  the  anchor  text 
from a script without reloading the entire page. 

URLs for Web Crawlers 

Human  readers  are  typically  smart  enough  to  figure  out  how  to 
navigate  to  another  page,  but  web  crawlers  are  not  that  smart. 
Search  engines  will  just  traverse  the  page  contents  to  find  links  to 
other  pages  and  request  those  pages.  If  the  links  are  handled  by 
JavaScript,  they  may  not  have  working  URLs  specified  at  all,  just  a 
JavaScript  handler  with  some  page  identifier  passed  as  a  parameter. 
For example, such links may look like this: 

<a href=”javascript:void()” onclick=”javascript:NavigateTo(‘page_42’)”> 

These  links  will  certainly  not be understood by web crawlers, and the 

online  documentation  will  not  be  indexed.  This  is  not  good  for  the 
SEO aspect of online documentation development. 

On  the  other  hand,  when  anchor  tags  are  used,  the  actual  URLs  are 
present  in  the  HTML  code,  and  everything  seems  to  be  fine.  These 
links typically look like this: <
​ a href=“page.html#anchor1”> 

 
19  Share this book:  
 

SEO and Technical Writing  

 

However,  anchors  are  perceived  as  on-page  navigation  means,  and 

web  crawlers,  just  like  web  browsers,  do  not  send  this  URL  part  to 
the  web  server  when  requesting  a  page.  As  a  result,  this still leads to 
a problem with content indexing by search engines. 

Hashbang for Navigation 

Google  solved  the  problem  of  indexing  webpages  with  AJAX 

navigation. In a few words: 

1. Let's  suppose  we  have  a  typical  URL  using  an  anchor  - 

www.example.com/ajax.html#key=value​. The Google solution was 
to  preserve  the  anchor  approach,  but  make  web  developers 
use  an  additional  symbol  -  an  exclamation  mark,  like 
this:​www.example.com/ajax.html​#!​key=value​. The ​#! symbols pair 
is  what  they  call  a  ​“hashbang”​.  The  exclamation  mark  is  a  part 
of  the  anchor  text,  so  it  can  be  programmatically  added  to  the 
URL even without the need for HTML 5 support. 
2. The  Google  crawler,  on  its  side,  understands  this  URL  format 
when  parsing  web  pages,  and  modifies  the  hashbang  URLs  to 
turn  the  anchor  part  to  a  URL  parameter,  which  will  go  to  the 
server  without  problems  when  requesting  this  resource  (unlike 
the  anchor  text):  ​www.example.com/ajax.html#!key=value 
converts  to 
www.example.com/ajax.html?_escaped_fragment_=key=value​.  This 
certainly  requires  the  webserver  to  understand  this  URL 
format.  However,  the  results  of  this  approach  are  a 
combination  of  AJAX  navigation and proper content indexing by 
search engines. 

 
20  Share this book:  
 

SEO and Technical Writing  

 

This process can also be represented in a visual form like this: 

ClickHelp  supports  the  hashbang  navigation  natively.  This  means 

that you get both benefits: 

● authors  and  readers  are  getting  nice  responsiveness  of  AJAX 

navigation; 
● web-crawlers  get  proper  links  they can use to index your online 
documentation. 

With  the  proper  AJAX  navigation  handling,  you  are  making  sure  the 
SEO  effect  of  your  online  documentation  is  strong  enough  to  add 
visibility to your company, and your website.  

Content Order 

The  order  of  words  in a text is used by search engines in the ranking. 

It is a known fact, which should be paid attention to. 

First  of  all,  the  ​beginning  of  the  text  is  very  important  for  search 
engines.  Therefore,  this  part  of  any  text  must  contain  keywords  and 
basic information about the content. 

 
21  Share this book:  
 

SEO and Technical Writing  

 

Secondly,  search  engines  pay  attention  to  the  ​order  of  words  in 
phrases.  Phrases  that  exactly match the keywords are ranked higher. 
But  the  order  of  the  words  should  be  natural.  Otherwise,  penalties 
may be applied to the rank by the search engines. 

So,  if we want the online documentation to bring the maximum value 
for  the  company  visibility,  we  need  to  make  sure the structure of the 
content  and  the  order  of  words  are  given  the  needed  attention. 
Apparently,  a  good  document  structure  is  helpful  for  the  readers  as 
well,  so  you  have,  at  least,  two  strong  reasons  to  approach  the 
document planning task with proper attention. 

In  ClickHelp,  there  is  a  useful  feature  related  to  the  content  order  - 
the  branding  functionality.  You  may  wonder  how  branding  is  related 
to  the  content  order.  You  can  ​configure  a  number  of  branding 
options  to  make  your  online  documentation  portal  use  your 
company’s  visual  style.  And  among  those  options,  you  can  configure 
the  header  logo  that  is  displayed  for  every  online  document,  its  “alt 
text”,  and  specify  a URL of some target page. Typically, this is the URL 
of  your  company  website,  and  your  company  or  product  logo.  And it 
is  very  nice  that  this  link  appears  at  the  top  of  every  page  in  your 
documentation  portal  -  this  will  be  perceived  by  web  crawlers  as 
important information, and it is! 

 
22  Share this book:  
 

SEO and Technical Writing  

 

Here is how our customer page looks:  

As  ClickHelp  provides  a  wide  range  of  branding  options,  you  can 
design  your  portal  as  you  wish  without  strong  CSS  knowledge.  You 
can learn more examples from our P ​ ortal Gallery​. 

Robots.txt 

Typically,  each  web  site  has  directories  and  pages  that should not be 

indexed  by  search  engines. For example, printed versions of web site 
pages,  pages  of  the  security  system  (registration,  authentication). 
There  may  also  be  directories  like  administrator  resources  folder, 
various technical folders. 

In  addition,  webmasters  may  want  to  give  additional  information 

about  indexing  to  search  engines.  For  example,  the  location  of  the 
sitemap.xml file. 

All  these  tasks  are  performed  by  the  ​robots.txt  file​.  It  is  just  a  text 
file  of  a  specific  format,  and  you  put  it  on  your  website  (to  the  main 
directory)  so  that  the  web  crawlers  know  how  to  properly  index  the 
web  site  contents.  The  full  specification  of  this  file  format  can  be 
 
23  Share this book:  
 

SEO and Technical Writing  

 

found  ​in  the  Google  Developers  portal​.  Also,  Google  Webmaster 

Tools  provide  tools  for  the  robots.txt  file  analysis  to  make  sure  you 
properly  created  the  file  -  this  function  is  in  the  ​Crawl  -  Blocked 
URLs  section.  So,  if  you  happen  to  see  some  strange  pages  of  your 
web  site  shown  in  the  search  results,  or  marked  as  indexed  in  the 
webmaster  tools  of  the  search  engine  you  are  using,  you  can  easily 
fix  this  by  creating  a  robots.txt  file.  There  are  a  lot  of  tools  on  the 
Internet that can help you generate correct file content. 

Please  note:  the  robots.txt  file  is  not  a  way  to  protect  sensitive 
pages,  it  is  just  a  set  of  directions  web  crawlers  may  follow  to  make 
sure  they  index  useful  content  and  not  service  pages.  The pages you 
restrict in the file will remain accessible by direct URLs, but will not be 
indexed. 

Robots.txt and Online Documentation 

When  it  comes  to  ​online  documentation  tools  or  the  tools  that  just 
publish  documentation  on  the  web,  there  are  also  pages  you  would 
like  not  to  be  indexed  to  avoid  confused  readers  when  they  come to 
a  page  that  was  not  supposed  to  be  directly  accessed  from  the 
search  results.  This  may  be  login  pages,  error  pages,  printer-friendly 
versions of documents, document property pages, user profiles, etc. 

Most  documentation  tools  that  generate  online  versions  of 

documentation  also  generate  a  number  of  service  pages.  So,  when 
publishing  documentation  online,  technical  writers  will  benefit  from 
understanding  the  contents  of  the  files  generated,  so  that  they  can 
create  a  good  robots.txt  file  to  avoid  indexing  certain  pages. 
Technical  writers  have  never  been  webmasters  to  think  about  this 
aspect,  but  now  they  may  have  to.  The  robots.txt  file  syntax  is  not 
complex  for  basic  tasks,  so  it  is  a  good  idea  to  check some examples 
and find out how to close a specific page or directory from indexing.  

 
24  Share this book:  
 

SEO and Technical Writing  

 

Lazy-Loading Images 

It's  not  a  secret  for  anyone  that  the  mobile  Internet  can  be  quite 
slow.  The  page  loading  speed  is  very  important  for  mobile-oriented 
pages.  And  it's  not  a  secret  either  that  ​Google  is  using the site speed 
as  an  SEO  factor​.  Also,  it  is  well-known  that  people  tend  to  leave  a 
web  site  if  it  does  not  open  within  3  seconds.  As  you  can  see,  there 
are plenty of reasons to improve the page loading speed. 

Improve Website Performance 

There  are  a  lot  of  ways  to  improve  the  performance  of  your  web 
pages.  But  lowering  the  content  size  and  the  number  of  requests  is 
probably  the  things  you  should  do  first.  Or,  second.  The  first  step  is 
to  enable  server-side  ​traffic  compression  and  caching​,  but  those 
are trivial things that leave no space for a creative approach. 

 
25  Share this book:  
 

SEO and Technical Writing  

 

If  your  pages  are  heavy,  they  probably  have  many  beautiful  images, 
and  you  don't  want  to  remove  those  as  a  way  to  improve  the  page 
loading  speed.  But  how  do  you  decrease  your  web  page  initial  load 
time,  downloaded  content  size  and  the  number  of  requests  -  all  in 
one, and without removing those nice pictures? 

When  a  web  page  opens,  visitors  see  only  the  first  part  of  it.  They 
don't  see  anything  below  the  fold.  What  if  you  could  tell the browser 
not  to  load  those  images  from  the  server  until  it  needs  to  display 
them?  Those  may  be big screenshots or small icons - if you have a lot 
of  them,  they  are  all  speed  killers.  And  the  solution  is  loading  the 
images on demand, or, as they say, lazy-loading the images. 

Handling Images - Typical Approaches 

There  are  several  approaches  to lazy-loading images, but the general 

idea  is  always  the  same:  you change your markup somehow to make 
below-the-fold  images,  which  are  not  essential  for  the  first  load, 
hidden  by  default.  Then,  you  handle  the  window.onscroll  event  in 
JavaScript.  When  the  page  is  scrolled  and  an  image  is  supposed  to 
become visible, you do some magic to make the browser load it. 

Before  we  start,  here  is  an  important  note  on  the  SEO  side  of 
lazy-loaded  images:  neither  of  the  approaches  described  in  this  post 
provide  proper  image  indexing.  However,  our  recommended 
approach,  unlike  others,  allows  people  with  disabled  scripts  to  see 
the  images.  Also,  it  gives  crawlers  a  chance  to  see  the  image  if  they 
ever  bother  to  index  background  images.  However,  there  is  a 
separate  solution  for  image  indexing:  you  can use ​image sitemaps to 
force  web  crawlers  to  index  your  images.  So,  first  of  all,  you  need  to 
 
26  Share this book:  
 

SEO and Technical Writing  

 

decide  whether  the  images  you  are  going  to  lazy-load  are  important 
for  your  web  site  and  whether  image  sitemaps  are  an  acceptable 
solution  for  you.  It  all  depends  on  your  specific  scenario,  but  the 
negative  SEO  effect  of  poor  page  performance  may  be  more 
significant than that of the non-indexed images. 

If  you  are  still  reading  this,  you  seem  to  be  serious  about  the 
lazy-loading  approach.  OK,  good!  So,  here  are  the  most  common 
magic tricks​ commonly used when implementing lazy loading. 

● Custom attributes to store the image URL 

 
In  the  HTML  markup,  use  a  custom  attribute  for  the  image  URL 
rather  than  putting  it  to  the  src  attribute.  Then  set  the  src  attribute 
from  JavaScript to make the browser load the image. Let's take a look 
at an example. Let's suppose, you have an image on your page: 
 
<​img​ ​src​=​"/images/screenshot​.p ​ ng"​/> 
 
To make it lazy-loaded, you convert the above code line to this: 
 
<​img​ ​src​="​ /images/blank​.p ​ ng" d
​ ata​-s​ rc​=​"/images/screenshot​.p
​ ng"​/> 
 
The  src  attribute  points  to  an  empty  image  just  to  make  the  markup 
valid. 
 
And  when  you  need  to  display  the  image,  your  script  simply  assigns 
the  value  of  the  data-src  (or  whatever)  attribute  to  the  src  attribute. 
You get something like this at runtime: 
 
<​img​ ​src​=​"/images/screenshot​.p ​ ng" 
data​-s​ rc​="​ /images/screenshot​.p ​ ng"​/> 

Is  it  a  good  solution?  No.  And  here  is  why.  Web  crawlers  and  visitors 
with  JavaScript  disabled  in  the  browser (some people say they do not 
exist,  but  we  saw  one  of  them  last  week)  will  never  see your image if 

 
27  Share this book:  
 

SEO and Technical Writing  

 

you  do  it  this  way.  Besides,  it  might  be  against your markup creation 
rules  to  use  custom  attributes.  Also, there is always a chance this will 
not  work,  because  official  support  for  custom  "data-" attributes have 
only been i​ ntroduced in HTML 5​. 

● Use invisible DIV elements 

 
Convert  images  to  invisible  DIVs  and  set  the  original  image  as  a 
background.  Then  make  those  DIVs  visible  from  JavaScript  when 
needed. Let's take a look into the details of this approach. So, it is sad 
enough  that  we  cannot  simply  prevent  a  browser  from  downloading 
an image described as this: 
 
<​img​ ​src​=​".​ ..​"​/> 
 
A  number  of  ​experiments  have  been  made  to prove this. However, if 
you  set  the  image  as  a  background  for  a  DIV  with  the  display:none 
style,  this  will  work  and  browsers  will  not  download  the  image!  Let's 
take a look at an example. 
Let's suppose, you have an image on your page: 
 
<​img​ ​src​=​"/images/screenshot​.p ​ ng"​/> 
 
To  implement  lazy  loading,  you  convert  it  to  something  like  this 
(yeah,  inline  styles  are  no  good,  they  are  here  just  for  the  sake  of 
simplicity): 
 
 
<​div​ s​ tyle​="​ display:none; 
background​-image:​url​(​'/images/screenshot.png'​);​width​: ​500​px; 
height​: ​300​px"​> 
</​div​> 
 
And when you need to display the image, you simply make the DIV 
element visible from JavaScript by changing the style. You get 

 
28  Share this book:  
 

SEO and Technical Writing  

 

something like this at runtime: 

 
<​div​ s​ tyle​="​ display:block; 
background​-image:​url​(​'/images/screenshot.png'​);​width​: ​500​px; 
height​: ​300​px"​> 
</​div​> 
 
Now,  it  is  just  the  standard  HTML  markup,  no  custom  stuff.  Do  you 
think  this  solution  is  good?  Well,  no.  Same  problem  as  before:  your 
image is not accessible without JavaScript. 
 
Besides,  if  you  check  such  a  page  with  ​Google  PageSpeed  Insights​, 
you  will  see  that  it  still  considers  all  the  negative  page  speed  effect 
caused  by  large  images,  just  as  if  they  were  loaded  in  the  very 
beginning.  This  means  that  even though your page will take less time 
to  load  in  browsers,  Google  will  not  give  you  extra  SEO  points  for 
this.  Also,  your  page  content  will  "jump"  when  the  hidden  DIV 
appears because its original size is zero - not a good thing for visitors. 
 

Handling Images - The Recommended Approach 

So, we want everything at once: 

● Improve the page load time in web browsers. 

● Get better SEO ranks from Google. 
● Make images visible with JavaScript disabled 

 
29  Share this book:  
 

SEO and Technical Writing  

 

Do  you  think we want too much? Nah, it is all possible! To accomplish 

this,  we  will  need  to  slightly  modify  approach  #2.  Below  are  the 
specific steps to follow. 

1. Prepare your content. 

 
Convert  an  image  to  a  DIV  with  a  background.  That  is,  get  this  code 
line: 
 
<​img​ ​src​=​"/images/screenshot​.p
​ ng"​/> 
 
Convert it to this form: 
 
<​div​ c​ lass​="​ lazyImg" 
style​="​ background-image:​url​('​ /images/screenshot.png'​);​width​: 5 ​ 00​px; 
height​: ​300​px"​> 
</​div​> 

Note​:  we  did  not  specify  the  display:none  style,  and  we  did  not 
declare  the  lazyImg CSS class anywhere. This makes the image visible 
by default, if no script runs. 

2. Declare the lazyImg class dynamically. 

Add the following script tag to the end of your page's <head> section: 
 
<​head​>  
<
​ !--The original content of the head tag goes here--> 
 
<​ s​ cript type="text/javascript"​>  
document​.​write​(​"<
​ style>.lazyImg{background-image:none 
!important;}</style>​")​ ;​  
< ​ /​script​> 
</​head​> 

Web  pages  are  compiled  from  top  to  bottom,  so  this  will  guarantee 
that  the  image  will  not  be  loaded  for  people  having  JavaScript 

 
30  Share this book:  
 

SEO and Technical Writing  

 

enabled.  Unlike  the  original  approach,  Google  PageSpeed  will  honor 

it  too.  Also,  the  space  intended  for  the  image  will  be occupied by the 
placeholder  DIV  element,  so  your  page  content  will  not  "jump" when 
the image is loaded. 

Important:  Do  not  apply  the  display:none  style  to  the  DIV.  If  you  do 
this,  the  code  below  (for  image  visibility  detection)  will  not  work 
properly, because the offsetTop property of the element will be zero. 
Basically,  that's  it  for  the  creative  part.  But  to  make  the  solution 
complete,  let  us  also  implement  the  JavaScript  logic  which  is  similar 
for any of the approaches we mentioned above. 

3. Handle the window.onscroll event. 

Now,  we  need  to  handle  the  window.onscroll  event  to  show  the 
image  dynamically.  To  do  this,  we  are  going  to  use  the  approach 
described h ​ ere​: 
 
isScrolled = ​ ​ ​false​; 
window​.​onscroll = ​ ​ f​ unction​ (​ )​ {​ ​ isScrolled ​=​ t​ rue​;​ }​ ; 
 
function​ onWindowScroll​() 
{ 
​if​ (​ i​ sScrolled​) 
​{ 
isScrolled = ​ ​ ​false​; 
… ​//Our lazy-loading code will go here 
​} 
} 
 
setInterval​(o ​ nWindowScroll​,​ ​100​);​  

The  idea  is  simple:  by  default,  your  browser  will  generate  lots  of 
onscroll  events  for  a  single  smooth  scroll  action.  So,  we  only  set  a 
flag  in  the  onscroll  event and check for the flag ten times per second. 

 
31  Share this book:  
 

SEO and Technical Writing  

 

If  the  flag  is  true,  we invoke our complex logic. This way, the complex 

logic will not affect your browser performance. 

Warning:  It  is  not  that  simple  for  mobile  browsers.  A  number  of 
experiments  demonstrate  that  mobile  browsers  fire  the  onscroll 
event  only  when  the  scrolling  ends,  but  not  during  the  process,  and 
there  is  no  proper  workaround  for  this.  So,  you  will  not  see 
lazy-loaded images until you stop scrolling on mobile devices. 

4. Collect all lazy-loaded images. 

Let  us  generate  a  list  of  all  delay  loaded  images  once  in  order  not  to 
check  them  on  every  scroll  action.  To  do  this,  we  will  select  all 
elements  having  the  "lazyImg"  class.  Note  that  there  can  be  more 
than  one  class  applied  to  an  element,  so  it  is  not  just  a  simple 
retrieval of elements by their class name. 
 
function​ getElementsByPartOfClassName​(p ​ artOfClassName​) 
{ 
​var​ allTags = ​ ​ document​.g ​ etElementsByTagName​("​ ​*"​ )​ ​; 
​var​ res = ​ ​ [​ ]​; 
​for​ (​ v ​ ar​ i ​=​ 0 ​ ;​ ​ i <
​ ​ allTags​.​length​;​ i​++) 
​{ 
​if​ (​ a
​ llTags​[i​ ​].​className & ​ & 
allTags​[i​ ]​ .​className​.i​ ndexOf​(​partOfClassName​)​ > ​ ​ -​ 1
​ ​) 
​{ 
res​.​push​(​allTags​[​i]​ )​; 
​} 
​} 
 

 
32  Share this book:  
 

SEO and Technical Writing  

 

​return​ res​; 
} 
 
lazyImages ​=​ getElementsByPartOfClassName​("​ lazyImg"​);​  
 
5. Check which images are visible above-the-fold. 
Now, it is time to write some code into our window.onscroll handler. 
 
function​ onWindowScroll​() 
{ 
​if​ (​ i​ sScrolled​) 
​{ 
isScrolled = ​ ​ ​false​; 
​var​ scrollTop = ​ ​ window​.p​ ageYOffset ?​ ​ window​.p
​ ageYOffset :​  
window​.​scrollTop ?​ ​ window​.s​ crollTop ​:​ 0 ​ ​; 
​for​ (​ v ​ ar​ i =
​ ​ ​0;​ ​ i ​<​ lazyImages​.l​ ength​;​ i​++) 
​{ 
​if​ ​(s​ crollTop + ​ ​ document​.d ​ ocumentElement​.​clientHeight -​  
lazyImages​[​i]​ .​offsetTop ​>​ 0 ​ )​  
​{ 
lazyImages​[i​ ​].​className = ​  
lazyImages​[​i]​ .​className​.r​ eplace​(​"lazyImg"​)​; 
​} 
​} 
​} 
} 

This is it! Now, it is time for some explanations: 

❖ The  scrollTop  variable  stores  current  scroll  position  in  pixels, 

which  indicates  how  far  the  browser  window  has  been  scrolled 
(retrieved in a cross-browser way). 
❖ In  the  loop,  we  enumerate  all  lazy-loaded  images  and  check 
whether  the  top  border  (offsetTop  of  the  image)  is  higher  than 
the  bottom  border  of the visible area (scrollTop + window client 
height). 
 
33  Share this book:  
 

SEO and Technical Writing  

 

❖ If  the  image  is  above  the  browser  window  bottom  border 
(above-the-fold),  we  remove  the  lazyImg  class  from  it.  As  a 
result,  the  original  image  specified  in  the markup is loaded as a 
background and the image is thus delay-loaded. 

Of  course,  you  can  optimize  the  code  - for example, remove handled 

images  from  the  array  or  use  a  more  complicated  markup/CSS  rules 
to  handle  multiple  elements  at once. But the sample above gives you 
the general idea. 

Lazy-Loading Images - Full Sample Code 

As  a  conclusion,  here  is  the  full  code  of  the  solution  in  the  order  in 
which it should appear on your web page: 

<​head​> 
​<!--The original content of the head tag goes here-->  
 
​<s​ cript type="text/javascript"​> 
document​.​write​(​"<​ ​style​>.​lazyImg​{​background​-i​ mage​:n​ one 
!​important​;}​</​style​>"​ )​ ;​  
​</​script​> 
</​head​> 
 
<!--Some page content goes here...--> 
 
<​div​ c​ lass​="​ lazyImg" 
style​="​ background-image:​url​('/images/screenshot​.p ​ ng’);​width​: ​500​px; 
height​: ​300​px"​></​div​> 
 
<!--Some more page content goes here...--> 
 
<​script src="/delay-load.js"​> 
</​script​> 

And here is the content of the d

​ elay-load.js​ file: 

 
34  Share this book:  
 

SEO and Technical Writing  

 

function​ getElementsByPartOfClassName​(p ​ artOfClassName​) 

{ 
​var​ allTags = ​ ​ document​.g ​ etElementsByTagName​("​ ​*"​ )​ ​; 
​var​ res = ​ ​ [​ ]​; 
​for​ (​ v ​ ar​ i ​=​ 0 ​ ;​ ​ i <
​ ​ allTags​.​length​;​ i​++) 
​if​ (​ a
​ llTags​[i​ ​].​className & ​ & 
allTags​[i​ ]​ .​className​.i​ ndexOf​(​partOfClassName​)​ > ​ ​ -​ 1
​ ​) 
res​.​push​(​allTags​[​i]​ )​; 
​return​ res​; 
} 
 
// Collect all delay-loaded images in the document 
lazyImages ​=​ getElementsByPartOfClassName​("​ lazyImg"​);​  
 
isScrolled = ​ ​ ​false​; 
window​.​onscroll = ​ ​ f​ unction​ (​ )​ {​ ​ isScrolled ​=​ t​ rue​;​ }​ ; 
 
function​ onWindowScroll​() 
{ 
​if​ (​ i​ sScrolled​) 
​{ 
isScrolled = ​ ​ ​false​; 
​var​ scrollTop = ​ ​ window​.p ​ ageYOffset ?​ ​ window​.p ​ ageYOffset :​  
window​.​scrollTop ?​ ​ window​.s​ crollTop ​:​ 0 ​ ​; 
​for​ (​ v ​ ar​ i = ​ ​ ​0;​ ​ i ​<​ lazyImages​.l​ ength​;​ i​++) 
if​ (​ ​scrollTop ​+​ document​.d ​ ocumentElement​.c​ lientHeight ​- 
lazyImages​[​i]​ .​offsetTop ​>​ 0 ​ )​  
lazyImages​[​i]​ .​className = ​  
lazyImages​[​i]​ .​className​.r​ eplace​(​"lazyImg"​)​; 
​} 
} 
 
setInterval​(o ​ nWindowScroll​,​ ​100​);​  

 
35  Share this book:  
 

SEO and Technical Writing  

 

Conclusion 
Online  documentation  can  be  a  powerful  boost  for  your  marketing 
and  business.  However,  keep in mind that SEO-friendly doesn’t mean 
that  your  documentation  should  look  like  a  list  of  keywords  to  make 
it  more  searchable.  SEO  is  just  a  tool,  not  a  goal, and the best way to 
make  your  docs  SEO-friendly  is  to  write  relevant  and  high-quality 
content,  create  human-readable  URLs,  minimize  page  load  time  and 
the  like  that  we’ve  described  above  to  make  your  users  read  your 
manuals  gladly  since  the  main  point  for  Google  is  how  readers  react 
to your webpages. 
 
In  order  to  improve  your  technical  writing,  ​subscribe  to  our blog and 
follow  us  on  ​Facebook​,  ​Twitter​,  ​Medium​,  ​Telegram  to  learn  more 
stories in this regard. 
 
Here are 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 
● Technical Writing: Readability and Text Metrics 
 
 
Good Luck with your technical writing! 
ClickHelp Team

 
36  Share this book:  
 

SEO and Technical Writing  

 

 
37  Share this book: