Documentation Writing Specifications
This writing specification outlines the requirements for the structure, content elements, and language style of documents in the openEuler docs repository to ensure a consistent style across openEuler documentation.
Before starting to write openEuler documentation, familiarize yourself with this specification. Improvement suggestions are welcome.
Document Structure Specifications
Feature manuals typically include an overview, background introduction, operational documentation (installation, deployment, and usage guide), frequently asked questions, and appendix. Developers may add or remove sections based on project needs. For reference, see the A-Tune example, which includes the content below.
Overview
Provide a brief introduction to the feature definition and functionality, followed by a description of the target audience.
Example:
This document describes how to install and use A-Tune, which is a performance self-optimization software for openEuler.
This document is intended for developers, open-source enthusiasts, and partners who use the openEuler system and want to know and use A-Tune. You need to have basic knowledge of the Linux OS.
Background Introduction
Background documentation should cover the feature context, introduction, and architecture. Common titles include: Understanding xxx
.
Operational Documentation
Requirements Specify the hardware and software environment, permissions, and other prerequisites needed to perform the operations.
Example:
markdownHardware requirements: xxx processor. Software requirements: openEuler version xx, root privileges.
Steps Operational steps include installation and deployment and usage instructions.
Guidelines for writing steps:
- Each step should describe a single action. Avoid combining multiple actions into one step.
- Clearly indicate optional conditions if steps are optional.
- For steps involving interface calls (such as tools or SQL statements), provide explanations for the interfaces used.
Result Verification Describe how to verify the correctness of the operation results. If verification is closely tied to a step, include it within that step. For example, the return information from executing an SQL statement.
Appendix
The appendix can provide definitions for terms and abbreviations.
Content Element Specifications
Naming
When creating new documents, add a MarkDown file (with the .md
extension) to the appropriate directory.
- Rule: Ensure the document name is unique and does not conflict with existing files. Rename if necessary.
- Rule: Use English for all document names.
- Rule: Avoid parentheses in file names, as they can disrupt directory display. Replace them with underscores (
_
) or hyphens (-
).
Example:
installation_and_deployment.md # Document for "Installation and Deployment"
Headings
- Rule: Headings should clearly and concisely summarize the section content without omitting key details.
- Rule: For procedural documents, use verb-object structures (for example, "Requesting Permissions"). Ensure consistency in heading structures for the same level and type.
- Rule: Avoid ending headings with punctuation. Use parentheses for additional context and exclude special characters like
?
. - Rule: Separate headings from body text with a blank line.
- Rule: Format headings with
#
followed by a space and the heading text. Increment heading levels one at a time, starting with the top-level heading.
Example:
# Level 1 Heading
## Level 2 Heading
### Level 3 Heading
#### Level 4 Heading
##### Level 5 Heading
###### Level 6 Heading
Body
Formatting instructions:
Italic: Enclose text in single asterisks (
*
) for italic formatting.txt*italic text*
Bold: Enclose text in double asterisks (
**
) for bold formatting.txt**bold text**
Bold italic: Enclose text in triple asterisks (
***
) for bold italic formatting.txt***bold italic text***
Escape: Use a backslash (
\
) to escape special characters.txt\<escaped markup symbol>
Rule: Always use the backslash (\
) to escape characters as required.
Rule: Separate consecutive escape characters with a space, for example, \{ \}
.
Rule: Maintain both Chinese and English versions of documentation. For translation support, contact liujingrong3@huawei.com or wudonger@huawei.com.
Images
Usage:


Rule: Place all images in the figures subdirectory of the document folder. For example, the A-Tune User Guide stores its images in this directory. Always use relative paths for references.
Rule: Only use original or properly licensed images to avoid copyright issues.
Rule: Position images adjacent to their relevant text sections.
Rule: The preferred image format is PNG, with JPG as an alternative. Images must not exceed 640 pixels in height or 393 pixels in width, and should ideally be under 150 KB in file size.
Rule: For screenshots, crop to focus on essential content within these dimensions. Use red borders or text labels to emphasize important details in graphics.
Example:

The ./
prefix in the path is mandatory for proper online display.
Code Blocks
Code examples illustrate how to implement specific features, serving as references for developers during coding and debugging.
Rule: Ensure the code is logically and syntactically correct. Rule: Clearly separate input and output sections where applicable. Rule: Include comments to explain critical steps in the code. Rule: Enclose inline code and commands in single backticks (for example, code snippet
). Rule: Format block code with either triple backquotes or four-space indentation (no TABs), preceded and followed by blank lines.
Examples
Inline code
markdownThe `printf()` function
Block code
python#!/usr/bin/env python3 print("Hello, World!")
c#include <stdio.h> int main(void) { printf("Hello world\n"); }
Lists
Unordered lists: Represented by asterisks (
*
), plus signs (+
), or hyphens (-
), each followed by a space. Maintain uniform markers within a list.markdown* First item * Second item * Third item + First item + Second item + Third item - First item - Second item - Third item
Ordered lists: Numbered items with a trailing period (
.
).markdown1. First item 2. Second item 3. Third item
Nested lists: Sub-items indented by four spaces (no TABs).
markdown1. First item: - Sub-item A - Sub-item B 2. Second item: - Sub-item A - Sub-item B
Rule:Use ordered lists when items follow a clear sequence or logical order.
Rule:Use unordered lists for parallel relationships or multiple-choice options.
Rule:Omit punctuation for terms or phrases in list items.
Rule:Include periods for complete sentences in list items.
Rule:If mixing phrases and sentences is unavoidable, apply periods to all items.
Rule:Alternatively, separate items with semicolons, ending the final item with a period.
Annotation Symbols
The following annotation symbols may appear in documentation to indicate different scenarios and levels of importance. Select the appropriate symbol based on the significance of the information being highlighted.
Symbol | Purpose/Meaning | Usage |
---|---|---|
Warning | Failure to follow this warning may cause task interruption or unexpected results, though recovery is possible. | > [!WARNING]Warning > Content |
Note | Provides helpful tips or useful reference information. | > [!NOTE]Note > Content |
Note
- Choose the appropriate annotation symbol based on the documentation context and apply the correct styling.
- Notes/Warnings can contain nested ordered/unordered lists, but avoid tables and code blocks.
- To prevent style breaks, ensure
>
remains continuous. - Keep note/warning content concise. Consider placing lengthy explanations in the main text or splitting them into sections. Avoid excessive empty lines within styled blocks.
Links
Rule: Verify link destinations exist to prevent navigation errors. Use standard Markdown syntax instead of HTML.
Examples:
- Website link
This is the link to the [openEuler website](https://www.openeuler.org/en/).
- Relative path
[CI Pipeline Rules](./ci_rules.md)
Tables
Rule: Use standard Markdown table syntax in documentation. Avoid HTML table formatting.
Example:
| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1 | Cell 2 |
| Cell 3 | Cell 4 |
Alignment options:
-:
Right-aligned content:-
Left-aligned content:-:
Centered content
Rule: Omit punctuation when all cells in a column contain terms/phrases.
Rule: Use periods when all cells contain complete sentences.
Rule: Apply periods uniformly if mixed content cannot be avoided.
Punctuation
Rule: For numbered/bulleted lists, use periods consistently if items are complete sentences. Omit punctuation if all items are phrases. Maintain uniformity: either apply punctuation throughout or omit it entirely.
Rule: Always use half-width (ASCII) numerals.
Rule: Reserve exclamation marks exclusively for warnings about critical consequences involving equipment safety or personal harm. Avoid exclamation marks in all other contexts.
Language Style Specifications
Rule: Submissions must exclusively pertain to openEuler features.
Rule: Content must not include sensitive information or material exhibiting strong racial/gender discrimination.
Rule: All submissions must be original work without intellectual property infringement.
Rule: Content must remain factual and objective. Avoid exaggerated promotional language.
Unacceptable documentation practices
Submitting excessive pull requests in a short timeframe via automated tools to address trivial issues (such as typos, grammar errors, date inaccuracies, and awkward phrasing) without substantive value.