Writing Documentation
Documentation is vital for any project as it enhances communication and ensures that information is clearly conveyed. Well-crafted documentation should be accessible, readable, and understandable to its intended audience. It helps consolidate the solutions developed and facilitates onboarding new team members. This guideline aims to outline key principles for writing effective documentation and provide an overview of Markdown components for structuring content.
General Rules¶
- Be Clear and Concise: Use simple language, avoid jargon, and present information in a direct and succinct manner.
- Organize Information Logically: Use headings, subheadings, and bullet points for clear structure.
- Provide Context: Offer necessary background information and clearly state the purpose of each section.
- Use Visual Aids: Include diagrams, screenshots, and other visuals to enhance understanding.
- Justify Design Decisions: Explain the reasons behind design choices, including benefits and alternatives.
- Update Regularly: Review and revise the documentation periodically to ensure it remains accurate and reflects any changes in the project.
Creating New Page¶
To create a new documentation page:
- create a new file in the folder that best fits the topic you're working on.
- ensure that you adhere to the hierarchical folder structure.
- use the appropriate file naming convention.
- add the page to the navigation.
- provide the correct metadata description.
- use rich Markdown components.
File Naming¶
- files should be in lowercase, using
-instead of spaces. - folders should be in lowercase and organized hierarchically.
Example
Navigation¶
To add a page to the navigation:
- edit the
navsection in themkdocs.ymlfile. - add a new entry under the appropriate category that corresponds to your page.
nav:
- Other Category:
- other-category/other-file.md
- Your Section Name:
- your-section-name/other-file.md
- Your Subsection Name:
- your-section-name/your-subsection-name/your-file.md # <-- YOUR ENTRY
Note
Order of entries in the file reflects the order in the documentation.
Metadata¶
Metadata allows you to edit various aspects of a documentation page. Currently, the documentation supports the following fields:
- Title
- Authors
- Date
- Version
Note
The title and authors are mandatory fields that must be included in the page metadata. Author's email address should be put after ,.
Example
Markdown¶
Documentation should be written in Markdown. By using various Markdown components, you can create engaging and accessible documentation.
Text Formatting¶
Basic formatting allows you to enhance text by applying styles such as bold, italic, and underline. It helps emphasize important information, improve readability, and structure content effectively.
Example
FIRO (FLASH Inspection Rover, also known as Facility Inspection Rover) is a mobile robot designed to operate in environments where human presence is restricted due to hazardous radiation levels. It is a student project developed mostly during Erasmus internships at the FLASH particle accelerator at DESY
- bold
- italic
- underline
- highlight
strike
**FIRO** (*FLASH Inspection Rover*, also known as *Facility Inspection Rover*) is a mobile robot designed to operate in environments where human presence is ==restricted due to hazardous radiation levels.== It is a ^^student project^^ developed mostly during Erasmus internships at the FLASH particle accelerator at DESY
- **bold**
- *italic*
- ^^underline^^
- ==highlight==
- ~~strike~~
Headers¶
Headers organize content into sections, making it easier to navigate and understand the structure of your documentation. They are useful for highlighting key topics, creating.
Lists¶
Lists organize information into clear, manageable points, making content easier to read and understand. They are useful for outlining steps, summarizing key points, or grouping related items.
Example: Basic list
Example: List with checks
Tables¶
Tables present data in a structured, grid format, making it easy to compare and analyze information. They are useful for displaying statistics, comparing features, or organizing detailed information systematically.
Example
Grids¶
Grids arrange content in a structured, multi-column layout, providing a visually appealing way to display related information. They are useful for organizing complex data, showcasing comparisons, or creating responsive designs in documentation.
Example
- HTML for content and structure
- JavaScript for interactivity
- CSS for text running out of boxes
- Internet Explorer ... huh?
<div class="grid cards" markdown>
- :fontawesome-brands-html5: __HTML__ for content and structure
- :fontawesome-brands-js: __JavaScript__ for interactivity
- :fontawesome-brands-css3: __CSS__ for text running out of boxes
- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
</div>
Code Blocks¶
Code blocks allow you to display formatted code snippets within your documentation, making it easier for readers to understand and replicate coding examples. They are essential for illustrating programming concepts, providing step-by-step instructions, and sharing command-line operations or configuration files in a clear and readable manner.
Example
Admonitions¶
Admonitions in documentation allow you to draw the user's attention to important issues. Using the appropriate type, such as notes, warnings, or tips, is key for effective communication.
Example
Note
This is note admonition
Warning
This is warning admonition. It is auto expanded
Danger
This is danger admonition. You can expand this admonition
Available Types¶
Note
Use for general important information or reminders.
Abstract
Summarize key points or concepts succinctly.
Info
Provide additional context or background information.
Tip
Share helpful advice or best practices.
Success
Indicate successful outcomes or positive results.
Question
Pose questions to engage readers or prompt thinking.
Warning
Highlight potential issues or cautionary advice.
Failure
Discuss failures or mistakes to avoid.
Danger
Alert users to critical issues or severe risks.
Bug
Document known bugs or issues in the system.
Example
Illustrate concepts with practical examples.
Quote
Highlight significant quotes or key statements.
Outdated
Marks outdated section of the documentation
Annotations¶
Annotations are little markers that can be added almost anywhere in document. When users click on or focus these markers, a tooltip appears with expandable content. You can use them to add additional content for some topics.
Example
The rover has builtin watchdog (1)
- A watchdog is a monitoring system or process designed to ensure that a computer system or application is functioning correctly and to detect and respond to failures or issues.
Pins¶
Pins allow for placing annotations on images, which can be useful for highlighting specific areas
pin-big: Enlarges the pin.pin-contrast: Creates a high-contrast pin.data-xanddata-y: Set the pin's position as a percentage on the image.data-id: Sets the index of the image to which the pin belongs. Indexing starts from0
Example
Carousel¶
The carousel feature allows for displaying multiple images in a slideshow format. Users can navigate through the images to get a comprehensive view.
Example
Example: Mixing with pins
Footnotes¶
Footnotes provide additional information or references without interrupting the flow of the main text. They are useful for citing sources, adding clarifications, or offering supplementary details.
Example
We use RadCon1 dosimeter as main component for radiation data collection submodule
Formulas¶
Formulas allow you to present mathematical equations and expressions clearly within your documentation. They are essential for explaining calculations, scientific concepts, and technical details accurately and concisely. Using LaTeX make formulas easy to read and use.
Diagrams¶
Diagrams visually represent complex concepts, processes, or relationships, making them easier to understand. They enhance documentation by providing clear, illustrative explanations that complement textual descriptions.
Example: Basic graph
%%{init: {'theme': 'dark'}}%%
graph LR
A(Start) --> B{Error?};
B -- Yes --> C[Debug];
B -- No --> H(stop);
C --> D[Test];
D --> E{Passes tests?};
E -- Yes --> G[Deploy];
E -- No --> C;
G --> H;Example: Quadrant chart
%%{init: {'theme': 'dark'}}%%
quadrantChart
title Rover components
x-axis Low complexity --> High complexity
y-axis Low priority --> High priority
quadrant-1 Critical
quadrant-2 To implement
quadrant-3 Nice to have
quadrant-4 To re-evaluate
Component A: [0.7, 0.9]
System B: [0.6, 0.3]
Procedure X: [0.4, 0.6]``` mermaid
%%{init: {'theme': 'dark'}}%%
quadrantChart
title Rover components
x-axis Low complexity --> High complexity
y-axis Low priority --> High priority
quadrant-1 Critical
quadrant-2 To implement
quadrant-3 Nice to have
quadrant-4 To re-evaluate
Component A: [0.7, 0.9]
System B: [0.6, 0.3]
Procedure X: [0.4, 0.6]
```
File Button¶
The File Button creates a link to a downloadable file. This allows you to highlight documents available for download. By default, the file will be opened by the browser (if the browser supports this feature). If you want to force the file to be downloaded rather than opened, add the download attribute to the link.
Example
The component datasheet is available here: IDC_F_datasheet.pdf or here (force download) IDC_F_datasheet.pdf
Video¶
Video allows you to embed a video directly into your web page.
-
Markus Hoffmann, MichaelFenner, Stanislav Chystiakov, Julien Branlard, Holger Schlarb, Bhaskar Mukherjee, RadCon a real-time Gamma Dosimeter for XFEL using PIN-Diode-Sensors, 2019 ↩