diff --git a/.gitlab-ci-simple.yml b/.gitlab-ci-simple.yml
index fe9bffce03ac46789526ae8ffd39ad7fd6bc13ea..49c819b6f3dc0bccefe6c6b4b121a9b271e8ff66 100644
--- a/.gitlab-ci-simple.yml
+++ b/.gitlab-ci-simple.yml
@@ -2,11 +2,6 @@
 # see https://hub.docker.com/repository/docker/konttipoju/tinytex
 image: konttipoju/tinytex:2020-04a
 
-# first we build the PDF, then validate it
-stages:
-  - build
-  - validate
-
 # build latex/thesis.tex -> latex/thesis.pdf using pdflatex
 # shell-escape functionality is required by the minted package
 build:
@@ -16,10 +11,10 @@ build:
     - latexmk -pdf --shell-escape thesis.tex
   artifacts:
     paths:
-    - latex/thesis.pdf
+      - latex/thesis.pdf
 
 # a validation prints "PASS + something" is the file is PDF/A conformant
 validate:
-  stage: validate
+  stage: test
   script:
     - pdfa-validate latex/thesis.pdf|grep '^PASS'
diff --git a/web/config.md b/web/config.md
index 2662361d231e769d2779678ad3f173c95b0fbf95..503de64bf78b368ad874abfd785fa65c6bfa811f 100644
--- a/web/config.md
+++ b/web/config.md
@@ -7,32 +7,33 @@ You're free to organize the project as you wish. A sane default structure
 looks like this:
 
  - root
-   - .gitlab-ci.yml: configures CI/CD
-   - .gitignore: configures git to ignore temp files
-   - utuftthesis.clss: document class description
-   - thesis.xmpdata: metadata for PDF/A generation
-   - latexmkrc: build instructions for latexmk
-   - thesis.tex: main document (links to sub-documents)
-   - bibliography.bib: biblioraphy data (multiple bibs also possible)
-   - section-X.tex: sub-documents for sections
-   - images/: embedded images
-   - sources/: embedded source code listings
+   - `.gitlab-ci.yml`: configures CI/CD
+   - `.gitignore`: configures git to ignore temp files
+   - `utuftthesis.clss`: document class description
+   - `thesis.xmpdata`: metadata for PDF/A generation
+   - `latexmkrc`: build instructions for latexmk
+   - `thesis.tex`: main document (links to sub-documents)
+   - `bibliography.bib`: biblioraphy data (multiple bibs also possible)
+   - `section-X.tex`: sub-documents for sections
+   - `images/`: embedded images
+   - `sources/`: embedded source code listings
 
 In case you're using LyX, the following extra files are needed (the tex
 files can be generated from the lyx files):
 
  - root
-   - utuftthesis.layout: document class configuration for LyX
-   - thesis.lyx: main document (links to sub-documents)
-   - section-X.lyx: sub-documents for sections
+   - `utuftthesis.layout`: document class configuration for LyX
+   - `thesis.lyx`: main document (links to sub-documents)
+   - `section-X.lyx`: sub-documents for sections
 
 The standard files included in the template consist of:
 
 - The `latex` directory contains the document root. Everything from
   this directory can be moved to the project root, but make sure you'll
-  update the Gitlab CI, too.
+  update the GitLab CI, too.
 - The `tests` directory can be deleted. It contains an extensive test
   suite for the template.
+- The `web` directory can be deleted. It contains this documentation.
 - The document class file `utuftthesis.cls` is always required.
 - The `*.lyx` and `*.layout` files are only needed if you decide to
   use [LyX](https://www.lyx.org/), and can be deleted in other cases.
@@ -43,15 +44,15 @@ The documents are typically edited with
   - TeX editors
   - generic editors
   - LyX
-  - hosted cloud services (ShareLaTeX, Overleaf, or even Gitlab Web IDE)
+  - hosted cloud services ([ShareLaTeX, Overleaf](sharelatex.md), or even GitLab Web IDE)
 
 The documents are compiled with
-  - TeX -> directly with TeX utilities (pdflatex/xelatex/tectonic) -> PDF
-  - TeX -> LaTeX frontend (mklatex, arara etc.) -> PDF
-  - LyX -> TeX -> one of the previous two -> PDF
-  - LyX -> PDF
-  - Integrated build system (ShareLaTeX / Overleaf) -> PDF
-  - CI/CD pipeline (Gitlab) -> PDF artifact / publish site
+  - TeX → directly with TeX utilities (pdflatex/xelatex/tectonic) → PDF
+  - TeX → LaTeX frontend (mklatex, arara etc.) → PDF
+  - LyX → TeX → one of the previous two → PDF
+  - LyX → PDF
+  - [Integrated build system (ShareLaTeX / Overleaf) → PDF](sharelatex.md)
+  - [CI/CD pipeline (GitLab) → PDF artifact / publish site](docker.md#setting-up-gitlab-cicd)
 
 Note that when using TeX utilities directly, you need to make sure the
 document has been fully processed. Usually this requires multiple
@@ -177,7 +178,10 @@ The PDF/A generation mechanism is described in more detail in the
 
 ## Using the template
 
-Start by cloning the whole template repository.
+### Git
+
+Start by cloning the whole template repository (or fork the project
+in GitLab).
 The following command line instructions can be used for setting up
 a new thesis (replace MYNAME with your utu username):
 
@@ -188,7 +192,7 @@ $ git remote add mythesis https://gitlab.utu.fi/MYNAME/mythesis
 $ git push -u mythesis master
 ```
 
-If you'd like to use the Gitlab CI script, considering setting up
+If you'd like to use the GitLab CI script, considering setting up
 the simplified CI pipeline that does not run the full test suite
 (invoke these commands in the thesis/ directory):
 
@@ -211,13 +215,39 @@ $ git remote -v
 $ git push
 ```
 
-The project can be compiled with latexmk (pdfTeX):
+### Latexmk (PdfTeX)
+
+PdfTeX is the default engine for compiling the template. It offers
+better compatibility with most features.
+
+When using latexmk, the project can be compiled like so:
 
 ```bash
 $ latexmk -pdf -shell-escape thesis.tex
 ```
-XeLaTeX version can be compiled like so (OpenType/TrueType fonts):
+
+### Latexmk (XeTeX)
+
+XeTeX / XeLaTeX version is required if you want to use
+OpenType/TrueType fonts.
+
+When using latexmk, XeLaTeX version can be compiled like so:
 
 ```bash
 $ latexmk -xelatex -shell-escape thesis.tex
 ```
+
+### LyX
+
+LyX provides a graphical WYSIWYM interface for editing TeX-like
+LyX documents that can be converted to TeX. The template distribution
+contains the `utuftthesis.layout` document class description file
+for the same `utuftthesis.cls` as the one used by TeX documents.
+
+Start by editing the provided `thesis.lyx`. The file has been configured
+to use the custom `utuftthesis` document class.
+
+Depending on your LyX version, you may need to enable `-shell-escape`
+from the global LyX settings. Follow the program's instructions.
+When updating your TeX distribution, LyX may require reconfiguration.
+This functionality is available via the tools menu.
diff --git a/web/docker.md b/web/docker.md
index 7e72ea72276f04e7bdf0fbc6112fa8fdf8599b30..b0f0de20bc4cfedf3b813e6d811892ed72a3c2d5 100644
--- a/web/docker.md
+++ b/web/docker.md
@@ -3,7 +3,7 @@
 
 A custom LaTeX build environment based on *Debian stable* has been developed
 using *Docker* based container technologies. The purpose of this container
-is to facilitate LaTeX document generation using Gitlab CI/CD pipelines. The
+is to facilitate LaTeX document generation using GitLab CI/CD pipelines. The
 same image can also be used for generating documents either using the standard
 command line prompt or as a backend for new middleware.
 
@@ -11,7 +11,7 @@ The container's TeX distribution is based on
 [TinyTeX](https://yihui.org/tinytex/) + TeX 'small' scheme + additional
 packages. See the [`Dockerfile`](Dockerfile) for a full list of installed
 TeX packages. In addition, a headless Java JRE is provided for
-[VeraPDF](https://verapdf.org/) powered PDF/A validation, poppler utils
+[VeraPDF](https://verapdf.org/) powered [PDF/A validation](pdfa.md), poppler utils
 for analyzing the generated PDF files (`pdfinfo`, `pdffonts` etc.), and
 python3 + pygments for pretty printing source code using the LaTeX
 [minted](https://ctan.org/pkg/minted) package.
@@ -19,35 +19,32 @@ python3 + pygments for pretty printing source code using the LaTeX
 Docker image available at Docker Hub: https://hub.docker.com/repository/docker/konttipoju/tinytex
 
 
-## Setting up Gitlab CI/CD
+## Setting up GitLab CI/CD
 
-The project's [Gitlab CI script](.gitlab-ci.yml) provides an rather complex
-example of using the Docker image in Gitlab in various ways (building documents,
+The project's [GitLab CI script](.gitlab-ci.yml) provides an rather complex
+example of using the Docker image in GitLab in various ways (building documents,
 asserting certain properties, validating PDF/A conformance).
 
 [This simplified version](.gitlab-ci-simple.yml) can be used instead:
 
 ```yaml
 # see https://hub.docker.com/repository/docker/konttipoju/tinytex
-image: konttipoju/tinytex:2019-12g
-
-# first we build the PDF, then validate it
-stages:
-  - build
-  - validate
+image: konttipoju/tinytex:2020-04a
 
 # build latex/thesis.tex -> latex/thesis.pdf using pdflatex
 # shell-escape functionality is required by the minted package
 build:
+  stage: build
   script:
     - cd latex
     - latexmk -pdf --shell-escape thesis.tex
-artifacts:
-  paths:
-    - latex/thesis.pdf
+  artifacts:
+    paths:
+      - latex/thesis.pdf
 
 # a validation prints "PASS + something" is the file is PDF/A conformant
 validate:
+  stage: test
   script:
     - pdfa-validate latex/thesis.pdf|grep '^PASS'
 ```
@@ -92,14 +89,14 @@ service needs to be active (try `systemctl start docker`).
 The build environment first needs to be fetched from Docker Hub:
 
 ```bash
-$ docker pull konttipoju/tinytex:2019-12g
+$ docker pull konttipoju/tinytex:2020-04a
 ```
 
 We can then list all the available container images:
 ```bash
 $ docker images
 REPOSITORY           TAG                 IMAGE ID            CREATED             SIZE
-konttipoju/tinytex   2019-12g            4e7da92afcfa        2 hours ago         765MB
+konttipoju/tinytex   2020-04a            4e7da92afcfa        2 hours ago         765MB
 debian               buster-slim         2dbffcb4f093        4 weeks ago         69.2MB
 ```
 
diff --git a/web/pdfa.md b/web/pdfa.md
index c2241a1a6f0be2cf8b274ca2e9e2babd99833a58..a02d1116dff0a53495df44e77831c7b08cbc6923 100644
--- a/web/pdfa.md
+++ b/web/pdfa.md
@@ -42,9 +42,11 @@ Note that PDF/A support is a rather new feature in LaTeX, e.g. the pdfx
 consider compiling with a more recent LaTeX distribution. The template
 has been tested with TeXLive 2017+.
 
+### VeraPDF (generic instructions)
+
 A free [VeraPDF](https://verapdf.org/) tool can be used to test if the
 resulting PDF files are PDF/A conformant. Unfortunately, the official
-VeraPDF distribution may not build. Use the 1.15-SNAPSHOT
+VeraPDF distribution may not build. Use the snapshot
 [version hosted at UTU gitlab](https://gitlab.utu.fi/jmjmak/veraPDF-apps)
 instead.
 
@@ -56,9 +58,18 @@ $ latexmk -pdf -shell-escape thesis.tex
 $ java -cp validator.jar org.verapdf.apps.GreenfieldCliWrapper --format text -v thesis.pdf
 ```
 
-The UTU build of the VeraPDF tool is also included in the
-[LaTeX Docker image](web/docker.md) and can be run by simply invoking
-`pdfa-validate <file.pdf>`. The [gitlab CI script](.gitlab-ci-simple.yml)
+### VeraPDF (Docker image)
+
+A headless Java 11 JRE is provided in the Docker image for VeraPDF
+powered PDF/A validation. The UTU build of the VeraPDF tool is also
+included in the [LaTeX Docker image](web/docker.md) and can be run by
+simply invoking:
+
+```bash
+$ pdfa-validate thesis.pdf
+```
+
+The [GitLab CI script](.gitlab-ci-simple.yml)
 in this project demonstrates the validation of CI/CD generated PDFs with
 this tool.
   
diff --git a/web/sharelatex.md b/web/sharelatex.md
index 11259413f112bb8f5d36b58f264d06605ed2294d..b25bda74e4527dc54dec68519dcc7ab71fcf487b 100644
--- a/web/sharelatex.md
+++ b/web/sharelatex.md
@@ -7,7 +7,7 @@ Press register at the top right corner to register for the service.
 See the general LaTeX document guide for configuring the template.
 
 The following set of screenshots describes the process of exporting the 
-thesis template from the Gitlab to ShareLaTeX (exporting to Overleaf
+thesis template from the GitLab to ShareLaTeX (exporting to Overleaf
 differs slightly, but this instruction can be applied):
 
 ## Step 1: export the project
diff --git a/web/vm.md b/web/vm.md
index 455091eeac77496a0302e96f8ebcbe9e0024997a..af9a21e747f2cdc39496bfd6931570983de910b9 100644
--- a/web/vm.md
+++ b/web/vm.md
@@ -12,12 +12,12 @@ The `utuvm-latex` virtual machine contains preinstalled versions of
   * LyX (for WYSIWYM editing)
   * Pandoc for generating LaTeX documents from markdown sources
   * TeX editors (Gummy, Texworks, Texmaker, Texstudio)
-  * Generic editors (Emacs, Vim, Geany, nano )
+  * Generic editors (Emacs, Vim, Geany, nano)
   * PDF reader (Evince)
   * Pygments for syntax highlighting (minted)
   * Seafile client for storing the documents in the University's
     Seafile server.
-  * Docker, systemd-nspawn
+  * [Docker](docker.md#compiling-the-thesis-using-docker), systemd-nspawn
 
 The virtual machine also comes with a modern browser (Chromium) for editing
 documents in ShareLaTeX and Overleaf.