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:

  markdown

  Hardware 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:

![alt text](./path/to/image.png)

![alt text](./path/to/image.png "optional title")

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:

![](./figures/ci_check_result.jpg)

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

  markdown

  The `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 (.).

  markdown

  1. First item
  2. Second item
  3. Third item

• Nested lists: Sub-items indented by four spaces (no TABs).

  markdown

  1. 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.

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.