.. include:: ../Includes.txt
.. highlight:: rst

.. _write-good-content:

=============================
Tips for writing good content
=============================


How people read on the web
==========================

People read differently on the web than they read print media.

.. pull-quote::

   "On the web, however, most of us scan information, jumping
   from one point of interest to the next, hoping to trip over
   some relevant facts. In fact, according to a study by the Norman
   Nielsen Group, your visitors will only ready between 20 and 28%
   of the words on your site."

   -- `"8 Tips for Better Readability" by Roby Collinge <https://usabilla.com/blog/8-guidelines-for-better-readability-on-the-web/>`__

This information is not specific to online documentation, it is about
information on the web in general. Nonetheless, we should consider
that information about reading on the Web at least partly
applies to reading online documentation as well.

So:

* Readers on the web often do not read, they scan (skim).
* Additionally, they often do not read entire manuals, they google for
  the information they are looking for and start reading there.


Tip 1: Write for online reading
===============================

* Make it easier for the reader who has not read previous pages.
* Make sure, the title is clear.
* Text with good formatting is easier to scan (see the next two 
  tips)
  
Tip 2: Use paragraphs
=====================

In any case, avoid long "walls of text". Give the eye something to cling to.  

Tip 3: Use subheaders
=====================

Look at `this page <https://iconshots.com/tutorials/web-development/why-https-is-important-and-why-should-every-website-switch/>`__

Imagine removing all the subheaders and then reading it.


Tip 4: Think about your audience
================================

What is the typical target audience of your text?
Put yourself in the shoes of your readers while writing.
Find someone from your target audience to read your text and
give feedback.


Tip 5: Use a consistent and clear vocabulary
============================================

Use specific (not ambiguous) language.


Tip 6: Write simple, short sentences
====================================

Keep the text as short as possible. Edit out anything that can be omitted
without loss:

.. pull-quote::

   "Vigorous writing is concise. A sentence should contain no unnecessary words, a
   paragraph no unnecessary sentences, for the same reason that a drawing should have no
   unnecessary lines and a machine no unnecessary parts."

   -- `Strunk & White: "The Elements of Style <http://www.jlakes.org/ch/web/The-elements-of-style.pdf>`__



Tip 7: Use a spellchecker
==========================

.. hint::

   Use a spellchecker that also points out grammar mistakes and gives
   recommendations for style improvements. Try out this
   `free online check <https://www.grammarly.com/grammar-check>`__ by
   Grammarly.


Tip 8: Use Stack Overflow to learn
==================================

Yes, `Stack Overflow <https://stackoverflow.com/>`__ can be a good teacher. Or, we
should add, its users are.

You may notice, there are some good
answers on StackOverflow, ideally formatted for readability, very well written
and structured. If you have not signed up for StackOverflow yet, do it now
and start writing questions and / or answers.

Advanced Stack Overflow users `often use number or
unnumbered lists <https://stackoverflow.com/a/927386/2444812>`__ and other formatting
elements.

Of course, it is better to keep the text on Stack Overflow as short as possible,
but if the text is longer than a paragraph, lists help to structure the text
and make it more readable.

Additionally, some users are very good at explaining things.

See how this `highly voted answer by Mysticial on branch prediction
<https://stackoverflow.com/a/11227902/2444812>`__ uses a railroad junction
analogy.

You can use the advanced search to search for `highly voted answers
<https://stackoverflow.com/search?tab=votes&q=score%3a1000%20is%3aanswer>`__,
but note that number of votes correlates with a number of factors. Quality is not always
the decisive factor (it also depends on whether the information is relevant for
a high number of users).


Tip 9: Read other documentation
===============================

* Ask yourself questions: What works for you, what doesn't?

Here are some tips:

* `Docker <https://docs.docker.com/get-started/>`__
* Google Developer: `Get Started With Analyzing Runtime Performance <https://developers.google.com/web/tools/chrome-devtools/evaluate-performance/>`__
* `use TYPO3 blog <https://usetypo3.com/9lts-api-classes.html>`__


Tip 10: Read your own content
=============================

When you write new content, finish it, **wait a few days**, and then read it again!


.. _write-good-content-resources:

Additional Resources
====================

* Daniele Procida: `"What nobody tells you about documentation <https://www.divio.com/blog/documentation/>`__
  (May 19, 2017) - A very good blogpost about different kind of manuals.
* `How to fix the 7 most common glitches in technical writing <https://www.writing-skills.com/the-7-most-common-mistakes-in-technical-writing-and-how-to-fix-them>`_
* `"8 Tips for Better Readability" by Roby Collinge
  <https://usabilla.com/blog/8-guidelines-for-better-readability-on-the-web/>`__
  is a very good resource. However, some of the tips do not concern you as
  a writer. They are only relevant for theme development. As a writer, skip
  right down to tip 5.
* `Strunk & White: "The Elements of Style <http://www.jlakes.org/ch/web/The-elements-of-style.pdf>`__
  is a classic. Many principles still apply.

You can find more in the :ref:`resources` section.