Documentation Guide

Table of Contents

1. Setting up and maintaining the project website
2. Style Guide
3. Diagrams
4. Generating PDFs from web pages

Setting up and maintaining the project website

• We use Jekyll to manage documentation.
• The docs/ folder is used for documentation.
• To learn how set it up and maintain the project website, follow the guide [se-edu/guides] Using Jekyll for project documentation.
• Note these points when adapting the documentation to a different project/product:
  • The ‘Site-wide settings’ section of the page linked above has information on how to update site-wide elements such as the top navigation bar.
  • In addition to updating content files, you might have to update the config files docs\_config.yml and docs\_sass\minima\_base.scss (which contains a reference to AB-3 that comes into play when converting documentation pages to PDF format).
• If you are using Intellij for editing documentation files, you can consider enabling ‘soft wrapping’ for *.md files, as explained in [se-edu/guides] Intellij IDEA: Useful settings

Style Guide

• Follow the Google developer documentation style guide

• Also relevant is the [se-edu/guides] Markdown coding standard

Diagrams

• See the [se-edu/guides] Using PlantUML

Generating PDFs from web pages

In order to support the additional styling made possible by some experimental/non-universal CSS features (such as the @page rule), we use PrinceXML to generate our documentation.

Simply run make-pdf.sh from the docs folder in order to build the PDFs. There is also a GitHub workflow to automatically generate the PDFs for the User Guide and Developer Guide on every release.