Documentation guide
Setting up and maintaining the project website:
- We use Jekyll to manage documentation.
- The
docs/
folder is used for documentation. - To learn how to set 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
anddocs\_sass\minima\_base.scss
(which contains a reference toEduMate
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 guidance:
-
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
Converting a document to the PDF format:
- See the guide [se-edu/guides] Saving web documents as PDF files