Overhaul of the user manual

[herzbube]

Current solution

The user manual is currently maintained as a monolithic text file (docs/MANUAL). The formatting uses a set of simple text structuring rules. It is parsed and converted to HTML at runtime by DocumentGenerator. SectionedDocumentViewController presents the user with a list of the manual sections. When the user selects a section the HTML content is presented to the user by DocumentViewController using an instance of WKWebView.

Pros of the current solution:

• The manual is available in-app for the convenience of the user.
• Easy maintenance of a text file with any text editor, combined with human readable simple formatting rules. In essence, the same pros that exist for markup systems such as Markdown or reST.
• Simple deployment of the manual into the app bundle as a single text file resource.
• No external libraries are used to process the text file resource.
• Document sections can be nicely presented to the user in a table view, with sections being grouped under a group header title.

Cons of the current solution:

• The formatting rules are a project invention, i.e. they are neither Markdown nor reST.
• The formatting rules are geared towards text-only content. Specifically they don't support embedding of images.
• The formatting rules do not support links from one part of the manual to another. This limitation is mainly due to the table view approach of presenting the manual to the user: Jumping between manual sections would require very awkward UI design.
• As the feature count of the project has grown over time, the monolithic text file approach has become problematic - the current manual file has over 2'500 lines.
• The manual is not available in its HTML form outside of the app.

Rationale for a change

The main rationale why the current solution needs to be changed is the pure-text approach of the manual. Without illustrations it can be very difficult to explain some aspects of the user interface - a prime example is the function of all the buttons.

A secondary rationale is that, in order to understand the app, the user may want to consult the manual in parallel to using the app. To a certain extent this is possible with the current solution, because the manual is presented in a separate tab of the UI, so to read the manual the user does not have to close the part of the app that they are currently interacting with - they only need to switch tabs. Nevertheless, they can never see the UI they want to know something about and the manual at the same time.

New solution

The new user manual solution shall have the following high-level properties:

• A widely-used text-based markup system must be used instead of a project-internal markup system.
• The markup system must support illustrations and interlinking between parts of the manual.
• It must be possible to maintain the manual across multiple files.
• It must be possible to transform the manual into a set of HTML pages.
• It must be possible to perform the transformation via command line so that the transformation can be embedded into any kind of build system.
• The user manual must be available in-app without Internet connection.
• As part of the release process the user manual must be published as a website that is accessible with any web browser.

Rationale for the in-app availability of the user manual: It might be tempting to just point the user to the public website to read the manual. However, the user manual must be seen as an integral part of the app, and the user should never find themselves in a situation where they cannot look up how something works just because an external resource is not available. Scenarios:

• The user fails to have an Internet connection at the moment.
• The user has an old device where they can't update the app anymore because the project dropped support for the iOS version that runs on that device. For some reason the project then switches the hosting of the user manual website. The old app version must still be able to provide a user manual.
• The project is discontinued and the user manual website is no longer available. Installed apps will continue to function despite the project having been discontinued, and they must still be able to provide a user manual.

[herzbube]

Markup systems

Wikipedia has an article with a list and comparison of Lightweight Markup Languages.

LMLs not to be considered are those tied to a specific application, such as wiki markup languages, or LMLs that are not widely-used.

These are the candidates:

• Markdown
• reST
• POD
• AsciiDoc

Markdown

The drawback of Markdown is that it has many flavours. There has been an effort to standardize the format under the name "CommonMark", but so far these efforts have not resulted in a final specification.

Basic Markdown and even CommonMark lacks various features, notably there is no support for definition lists or tables. This support is then added by flavours such as GitHub Flavored Markdown, or Djot.

If Markdown is selected, then one of the flavours must be selected to support the missing features. Whether a flavour is eligible is then determined by the requirements for transforming into HTML.

reST

reSTructuredText (reST) is used mainly by the Python community to document Python and Python libraries/programs.

There is a clean specification for reST and it is widely used. The Sphinx document generator, and by extension also the documentation hosting platform Read the Docs use reST.

POD

Plain Old Documentation (POD) is used for documenting Perl and Perl modules/programs.

It lacks support for tables and therefore is not eligible.

AsciiDoc

Similarly to Markdown, AsciiDoc is not tied to a specific programming language community. It is more feature-rich than Markdown, however, and has a single specification which is currently being standardized by the Eclipse Foundation.

[herzbube]

Website hosting

There are roughly these 3 options:

• Hosting on dedicated server
• Hosting on GitHub via GitHub Pages
• Hosting on Read the Docs. Requires Sphinx and, consequently, reST.

[herzbube]

Generators

• Sphinx. Requires reST.
• MkDocs. Requires Markdown.
• Pandoc. Seems super-flexible, can process reST, AsciiDoc and also all sorts of Markdown flavours.
• Hugo: A generic website generator that I already use for my personal website. Has built-in support for all sorts of Markdown flavours (via the Goldmark processor), but can also be configured so that it can process AsciiDoc or reST.

[herzbube]

Final solution:

• Markup system: Markdown (GitHub Flavored Markdown), optionally AsciiDoc
• Generator: Hugo
• Website Hosting: GitHub Pages (https://littlego-usermanual.herzbube.ch/)