Fixed typos, improved alt text

adoption.rst

@@ -35,7 +35,7 @@ bodies of documentation. In some cases the adoption remains partial or is still
 * `edo <https://edo.readthedocs.io>`_, a library for Evolutionary Dataset Optimisation
 * `Encore <https://encore.dev/docs>`_, a framework for rapid backend development
 * Ericsson (internal)
-* Google's `Fuschia operating system <https://fuchsia.dev/>`_ 
+* Google's `Fuchsia operating system <https://fuchsia.dev/>`_ 
 * `Gatsby <https://www.gatsbyjs.com/docs/>`_
 * `Gensim <https://radimrehurek.com/gensim/auto_examples/index.html>`_, `How to Author Gensim Documentation
   <https://radimrehurek.com/gensim/auto_examples/howtos/run_doc.html>`_

explanation.rst

@@ -9,7 +9,7 @@ About explanation
 ===========
 
 ..  image:: /images/overview-explanation.png
-    :alt: 'Explanation - understanding oriented, theoretical knowledge, that serves our study'
+    :alt: Explanation - understanding oriented, theoretical knowledge, that serves our study
     :class: floated
 
 Explanation clarifies, deepens and broadens the reader’s understanding of a subject.
@@ -76,7 +76,7 @@ Analogy from cooking
 --------------------
 
 ..  image:: /images/mcgee.jpg
-    :alt: 'a child cooking'
+    :alt: 
     :class: floated
 
 In 1984 Harold McGee published *On food and cooking*.

how-to-guides.rst

@@ -9,14 +9,14 @@ About how-to guides
 ===========
 
 ..  image:: /images/overview-how-to.png
-    :alt: 'How-to guides - task oriented, practical steps, that serve our work'
+    :alt: How-to guides - task oriented, practical steps, that serve our work
     :class: floated
 
 How-to guides can be thought of as recipes, directions that guide the reader through the steps to achieve a specific
 end.
 
 Examples could be: *how to calibrate the radar array*; *how to use fixtures in pytest*; *how to configure
-reconnection back-off policies*. On the other hand, *how to build a web application* is not - that's not a
+reconnection back-off policies*. On the other hand, *how to build a web application* is not - that's not
 addressing a specific goal or problem, it's a vastly open-ended sphere of skill.
 
 How-to guides matter not just because users need to be able to accomplish things: the list of how-to guides in your
@@ -67,13 +67,13 @@ Food and cooking
 --------------------
 
 ..  image:: /images/old-recipe.jpg
-    :alt: 'a recipe'
+    :alt: A recipe contains a list of ingredients and a list of steps.
     :class: floated
 
 Consider a recipe, an excellent model for a how-to guide. A recipe clearly defines what will be achieved by following
 it, and **addresses a specific question** (*How do I make...?* or *What can I make with...?*).
 
-It's not the responsibility of a recipe to *teach* you how to make something. A professional chef who has made the
+It's not the responsibility of a recipe to *teach* you how to make something. A professional chef who has made
 exactly the same thing multiple times before may still follow a recipe - even if they *created* the recipe
 themselves - to ensure that they do it correctly.
 
@@ -131,7 +131,7 @@ Omit the unnecessary
 ~~~~~~~~~~~~~~~~~~~~~
 
 In how-to guides, **practical usability is more helpful than completeness.** Whereas a tutorial needs to be a complete,
-end-to-end guides, a how-to guide does not. It should start and end in some reasonable, meaningful place, and require
+end-to-end guide, a how-to guide does not. It should start and end in some reasonable, meaningful place, and require
 the reader to join it up to their own work.
 
 

how-to-use-diataxis.rst

@@ -96,7 +96,7 @@ There's a strong urge to work in a cycle of planning and execution in order to w
 only way, and there are often better ways when working with documentation.
 
 ..  figure:: /images/always-complete.jpg
-    :alt: ''
+    :alt:
 
     Illustration copyright `Linette Voller <https://linettevoller.com>`_ 2021, reproduced with kind permission.
 

index.rst

@@ -43,7 +43,7 @@ Technical documentation should be structured explicitly around these four types,
 distinct from each other.
 
 .. image:: /images/diataxis.png
-   :alt: 'Diátaxis'
+   :alt: Diátaxis
 
 In other words, what we call *documentation* is fundamentally not one thing, but four. Understanding the implications
 of this, and how those four different things work, can help improve most documentation.

introduction.rst

@@ -62,7 +62,7 @@ either with serving *our acquisition* or *our application* of knowledge. Hence t
 of documentation are laid out:
 
 .. image:: /images/diataxis.png
-   :alt: 'Diátaxis'
+   :alt:
 
 
 ================
@@ -111,7 +111,7 @@ Characteristics of documentation
      - a reference encyclopaedia article
      - an article on culinary social history
 
-A clear advantage of organising material this way is that provides both clear *expectations* (to the reader) and
+A clear advantage of organising material this way is that it provides both clear *expectations* (to the reader) and
 *guidance* (to the author). It's clear what the purpose of any particular piece of content is, it specifies how it
 should be written and it shows where it should be placed.
 
@@ -130,19 +130,19 @@ documentation).
 * *tutorials and how-to guides* both describe *practical steps*
 * *how-to guides and technical reference* are both concerned with the *application of knowledge*
 * *reference and explanation* both contain *theoretical knowledge*
-* *tutorials and explanation* are both concerned with the *acquistion of knowledge*
+* *tutorials and explanation* are both concerned with the *acquisition of knowledge*
 
 Allowing these distinctions to blur is what brings about structural problems. The most common is a complete or partial
 collapse of tutorials and how-to guides into each other, while explanation spills over into both tutorials and
 reference material:
 
 .. image:: /images/partial-collapse.png
-   :alt: 'Partial collapse'
+   :alt: A structure on the verge of collapse
 
 But sometimes, documentation actually looks like this:
 
 .. image:: /images/total-collapse.png
-   :alt: 'Total collapse'
+   :alt: A totally collapsed structure
 
 -------------
 

reference.rst

@@ -9,7 +9,7 @@ About reference
 ===========
 
 ..  image:: /images/overview-reference.png
-    :alt: 'Reference - information oriented, theoretical knowledge, that serves our work'
+    :alt: Reference - information oriented, theoretical knowledge, that serves our work
     :class: floated
 
 The only purpose of a reference guide is to describe, as succinctly as possible, and in an orderly
@@ -50,7 +50,7 @@ Food and cooking
 --------------------
 
 ..  image:: /images/liquorice.png
-    :alt: "Wikipedia's entry for liquorice"
+    :alt: Wikipedia's entry for liquorice
     :class: floated
 
 Perhaps you might consult an encyclopaedia to read about an ingredient (for example, about
@@ -92,8 +92,9 @@ at the same time.
 In the case of code, this means arranging the sections of reference documentation to follow the
 architecture of the software, where possible.
 
-It doesn't mean forcing the documentation into an unnatural structure. What's important is the that logical, conceptual
-arrangement of and relations within the code should help make sense of the documentation.
+It doesn't mean forcing the documentation into an unnatural structure. What's important is that the
+logical, conceptual arrangement of and relations within the code should help make sense of the
+documentation.
 
 
 Be consistent

tutorials.rst

@@ -8,7 +8,7 @@ About tutorials
 ===========
 
 ..  image:: /images/overview-tutorials.png
-    :alt: 'Tutorials - learning-oriented guides that describe practical steps and are intended to serve our study.'
+    :alt: Tutorials - learning-oriented guides that describe practical steps and are intended to serve our study.
     :class: floated
 
 A tutorial must help a beginner achieve basic competence with a product, so that they can go on to use the product
@@ -23,7 +23,7 @@ it's concerned with *skill*: practical, not theoretical knowledge.
 Having completed a tutorial, the learner should be in a position to start to make sense of the rest of the
 documentation, and the product itself.
 
-For a product, tutorials turns new learners into users. An inadequate tutorial can prevent a project from
+For a product, a tutorial turns new learners into users. An inadequate tutorial can prevent a project from
 acquiring new users.
 
 =================
@@ -33,7 +33,7 @@ The tutorial as a lesson
 -------------------------
 
 A lesson entails a relationship between a teacher and a pupil. In all learning of this kind, **learning takes place
-through what the the pupil does**.
+through what the pupil does**.
 
 Any facts and explanations that are presented in teaching are almost irrelevant to what the pupil will learn - what
 matters is what the teacher gets the pupil to do.
@@ -45,7 +45,7 @@ experience, your tutorial isn't doing the job it needs to.
 Obligations of the teacher
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**The teacher has responsibility**, for what the pupil is to learn, what the pupil will do in order to learn it, and
+**The teacher has responsibility**: for what the pupil is to learn, what the pupil will do in order to learn it, and
 for the pupil's success. The only responsibility of the pupil is to be attentive and to follow the teacher's directions
 as closely as they can. **There is no responsibility on the pupil to learn, understand or remember** - the learner's
 *only* obligation in this contract is to do things as directed.
@@ -77,8 +77,8 @@ again to ensure that the tutorial still performs its required functions.
 
 Finally, you will find that no other part of your documentation is subject to revisions the way your tutorials are.
 You only have to change a reference or how-to guide if something in the product changes, and even then, usually only
-part of it needs to change. In the case of a tutorial you may come to the conclusion that the whole lesson should be
-completely rewritten, because you have thought of a better way produce a learning experience for the pupil.
+part of it needs to change. In the case of a tutorial, you may come to the conclusion that the whole lesson should be
+completely rewritten, because you have thought of a better way to produce a learning experience for the pupil.
 
 You can easily find that writing and maintaining your tutorials occupies as much time and energy as the the other
 three parts put together.
@@ -89,7 +89,7 @@ Food and cooking
 --------------------
 
 .. image:: /images/anselmo.jpg
-   :alt: 'a child cooking'
+   :alt: 
    :class: floated
 
 
@@ -197,7 +197,7 @@ they see a result from their actions. As far as possible, the effect of every ac
 possible. The relation of cause and effect should be evident. Finally, each result should be something that the user
 can see as meaningful.
 
-**Every step the learner follows should accomplish produce a comprehensible result, however small.**
+**Every step the learner follows should produce a comprehensible result, however small.**
 
 
 Make your tutorial repeatable
@@ -225,7 +225,7 @@ pattern in them and seek an abstract account of what is happening - until that t
 levels of abstraction before they have even had a chance to grasp the concrete is confusing and places unnecessary
 burdens on them.
 
-It's hard to resist this temptation, because once we have grasped something, we rely on the power of abstraction to
+It's hard to resist this temptation, because once we have grasped something, we rely on the power of abstraction
 to frame it to ourselves - and that's how we want to frame it to others. But it's simply not how learning or
 successful teaching works.