Documentation Style Guide#
dicehub documentation guidelines is based on the excellent documentation styleguide by GitLab and has been modified to dicehub's requirements.
This documentation is intended as the single source of truth and serves as a guide on how to write the documentation for dicehub.
This document defines the standards for documentation content.
Types of documentation#
It is best practice to have only these types of documentation:
Link instead of summarize#
Avoid summarizing to have multiple places with the same information, link instead.
All documentation is written in Markdown.
HTML in Markdown#
Hard-coded HTML is valid as long as:
- There is no equivalent in Markdown
- Advanced tables are necessary
- Special styling is required
- It has been approved and introduced as a special rule by the team
- dicehub (requires lower
- Python (requires capital
To lint your files, use the following command:
The documentation is organized by topics and not by types.
Folder structure overview#
The documentation is separated by these main topics:
All other directories are additional topics which can not be attributed to the preceding topics. The can exist on their own or in multiple topics, for example
API can be inside User, Administration or Development.
The table below shows what kind of documentation belongs in which directory.
|Directory||What belongs here|
| ||User related documentation. Everything related to the dicehub concept and its features.|
| ||Documentation related to the development of dicehub.|
Work with directories and files#
- When you create a new directory, always start with an
index.mdfile. Do not use another file name and do not create
- Do not use special characters and spaces, or capital letters in file names, directory names, branch names, and anything that generates a path.
- When creating a new document and it has more than one word in its name, make sure to use underscores (
_) instead of spaces or dashes (
-). For example, a proper naming would be
create_project_as_admin.md. The same rule applies to other files.
- Do not upload video files to the product repositories. Link or embed videos instead.
Use your best judgment to place documents and then ask the reviewer of your MR to confirm your decision.
Do not include the same information in multiple places.
Structure within documents#
- Structure content in alphabetical order in tables, lists, and so on, unless there is a logical reason not to.
- Keep it as short as possible, be clear and concise.
- Write in US English with US grammar.