Skip to content

Yi Documentation Contribution Guide

GloriaLee01 edited this page Feb 23, 2024 · 55 revisions

Doc Repo

Yi Repository Structure
│
├── README // Readme platform headers of Hugging Face, ModelScope, WiseModel
│
├── VL // Readme and images of Yi vision language model
│
├── assets // Images used in readme of Yi large language model
│
├── docs // Documentation files of Yi large language model
│
├── README.md // English readme
│
└── README_CN.md // Chinese readme

Using full web addresses (absolute paths) in documents

Why this is important:

  • Universal compatibility: our documents are not only hosted on GitHub but are also shared with platforms like Hugging Face, ModelScope, and Wise Model. these platforms display the content directly from GitHub.

  • Avoid broken links: using shorter web addresses (relative paths) can lead to broken links on platforms other than GitHub. to ensure all links and images work correctly everywhere, we use full web addresses (absolute paths).

Steps for using full web addresses:

  • Locate your image: go to the GitHub page where your image is located.

  • Copy the image address: right-click on the image and choose "Copy Image Address". ensure the URL ends with raw=true (e.g.https://github.com/01-ai/Yi/blob/main/assets/img/yi_34b_chat_web_demo.gif?raw=true. This is how GitHub handles direct links to images).

  • Use the full address: in your document, use this full address for images and links. this ensures they display correctly on every platform where the document is available.

For more information about full web addresses, see How to get "raw" links from GitHub (getting the raw image link).

Limitations of Managing Emoji Usage in Hugging Face Website Document Titles

  • Limitation 1: The effectiveness of Hugging Face's built-in Table of Contents (TOC) feature may be restricted by the limited awareness of its existence among most users.

  • Limitation 2: The use of Hugging Face website URLs may be constrained by its inability to support real-time synchronization with the GitHub readme document.

  • Limitation 3: Removing emojis from document titles may pose limitations by potentially reducing document readability.

Yi Writing Style Guide

Language and grammar

Abbreviations

General guidelines

Avoid abbreviations when the following conditions are true:

  • Their meanings are unclear.
  • They make the information more difficult to understand.
  • They occur infrequently in the information, for example, only two or three times in a large amount of content.
  • They are derived from Latin.
  • They abbreviate names or entities that are owned by other companies, and the owning company does not use those abbreviations.
  • They might be a registered trademark for a different product or entity.

Latin abbreviations

​​Do not use Latin abbreviations; use their English equivalents instead. Latin abbreviations are sometimes misunderstood.

Do Not use Latin abbreviation ❌ Use English equivalent ✅
e.g. for example
etc. Use and so on when you list a clear sequence of elements, such as “1, 2, 3, and so on” or “Monday, Tuesday, Wednesday, and so on.” Otherwise, rewrite the sentence to replace etc. with something more descriptive, such as “and other output.”
i.e. that is

Active Voice

Whenever possible, use active voice instead of passive voice.

  • In active voice, the subject of the sentence is the doer of the action. This is especially important when describing an action that should specify who or what is doing the action.
  • In passive voice, it's easy to neglect to indicate who or what is performing a particular action. In this kind of construction, it's often hard for readers to figure out who's supposed to do something (such as the reader, the computer, the server, an end user, or a visitor to a web page).

Example

  • Send a query to the service. The server sends an acknowledgment. ✅
  • The service is queried, and an acknowledgment is sent. ❌

Tense

  • Write in the simple present tense as much as possible if you are covering facts that were, are, and forever shall be true. Example
    • When you open the latch, the panel slides forward. ✅
    • When you open the latch, the panel will slide forward. ❌
  • Use past or future tense only when you cannot use present tense or it does not make sense to use the present tense. Example
    • If you select New in the previous window, the current window displays the recommended default values. ✅
    • If you select New in the previous window, the current window will display the recommended default values. ❌

Pronouns

Contractions

Capitalization

Miscellaneous

Punctuation

Commas

Exclamation points

Period

Formatting and organization

Numbers and measurements

Computer interface

Miscellaneous

Writing for diverse audiences

Glossaries

A

Admonition

You can use Tip, Note, Caution, and more admonitions.

  • Tip: provides helpful hints for completing a task. Do not use a tip to give essential information.
  • Note: contains additional information to emphasize or supplement important points of the main text.
  • Caution: indicates deprecated features or provides a warning about procedures that have the potential for data loss.

Usage rules

  • Use admonitions to call attention to information.
  • Use them sparingly, and never have an alert box immediately follow another alert box.
  • Too many notes can make topics difficult to scan. Instead of adding a note:
    • Re-write the sentence as part of a paragraph.
    • Put the information into its own paragraph.
    • Put the content under a new subheading.

L

Later

When referring to a range of version numbers:

  • Do not use above / up version ❌ Reason: version numbers should be essentially viewed as timeline markers rather than quantity markers.
  • Use earlier / later version ✅
  • “higher” version is not wrong and it is used in some product manuals, however, it is recommended to use “later” in Pulsar documentation to standardize on one expression for greater consistency in presenting the information to users.❗️

R

recommend

Avoid if possible. A phrase such as “We recommend that you take the following action” could create a potential marketing or legal problem

Grammar

Use prepositions with relative pronouns

  • The name of the topic that the message is published to. ✅
  • The name of the topic to which the message is published.

Reference

Pulsar Documentation Writing Style Guide

Clone this wiki locally