Skip to main content
Version: Next

Style Guide

The style guide helps keep the overall style of the documentation consistent, presenting a consistent experience to the user.

Technical writers recognized the importance of specifications early on, and communities like Write the Docs bring together the collective wisdom of writers to create best practices for software documentation.

Key points​

Documentation source file is in Markdown format, generated by Docusaurus, and follows the DevOps principles of CI.

You should follow below points of want to contribute to Websoft9 documentation:

  • Documentation changes must be submitted to PR for review and merging.
  • For third-party products, prioritize the presence or absence of functionality (point and click), followed by references and links, and avoid writing how-tos.
  • If the answer already exists in the documentation, use a link.
  • Use text as much as possible for clarification, reduce the use of screenshots.
  • Try to use a consistent style guide and words list
  • The main language of the documentation must be considered for translation into other languages to make the work of AI and machine translation easier and more accurate.

Automation​

Most of the files of documentation are manually written in Markdown.And soome files created by an automation.

There are currently two GitHub Action automated production files:

  • GitHub Action automated production files: json2md.yml, app_header.yml
  • Static Site Builder automated navigation: left main navigation, page content navigation

Image​

Images are preferred to be stored in the assets folder in the same directory as the md file, e.g

  • Directory path for application docs: docs/apps/appname/assets
  • Directory path for Websoft9 backup docs: docs/admin/backup/assets

Recommendations for naming image file

  • Websoft9 platform image name: websoft9_xx_xx_version.png
  • Application image name: appname_xx_xx_websoft9.png

Multilingual translation​

The basic principle of translation is to synchronize and translate the content into the main language without any expansion, abridgement, or interpretation based on the original version in the main language.

The basic process of translation:

  1. Each page change in the main language must automatically generate an issue for the corresponding translated page.

  2. Translate the content of the documentation.

    • Text is translated by AI and machine translation
    • Images need to be replaced according to the language

Application's documentation​

The application is not owned by Websoft9, so the primary goal in writing the application documentation is to help the user get up and running immediately, with a secondary goal of providing direction.

Principles to follow:

  • Creating md files from templates

  • Section principles

    • Getting started section, which aims to help users get started immediately with initialization, backend usage, etc.
    • Configuration options section, give user with correct information about functionality with or without.
    • Administrator section is a quick guide to the official documentation.

  • No additional subtitles are recommended for either the Configuration Options or Administrator sections.

Specifications not listed above follow the standards below: