Writing User Manual
Creating a user manual is essential for helping users understand and effectively utilize a product or service. A well-structured user manual improves user experience and supports users in resolving issues independently. This guideline provides key principles for writing an effective user manual and an overview of Markdown components for organizing content.
General Rules¶
- Be Clear and Concise: Use simple language, avoid technical jargon and use step-by-step instructions.
- Organize Information Logically: Use headings, subheadings, and bullet points for clear structure, and include a table of contents if the document is lengthy.
- Provide Context: Offer an introduction and explain the manual’s purpose.
- Use Visual Aids: Add screenshots, diagrams, and captions for clarity.
- Update Regularly: Revise to reflect product changes and keep instructions accurate
Creating New Page¶
To create a new user manual 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. siusiak
- 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 user manua.
Metadata¶
Metadata allows you to edit various aspects of a user manua page. Currently, the user manua 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
Author's email address should be put after ,
Markdown¶
User manual should be written in Markdown. By using various Markdown components, you can create engaging and accessible user manual.
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 user manua. 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 user manua.
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 user manua, 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 user manua 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 user manua
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 user manua. 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 user manua 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: writing-user-manual.md or here (force download) writing-user-manual.md
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 ↩