Skip to content

Latest commit

 

History

History
131 lines (74 loc) · 7.17 KB

CONTRIBUTING.en-US.md

File metadata and controls

131 lines (74 loc) · 7.17 KB
Raw

Contribution Guide

Welcome to the Documentation! This guide aims to facilitate contributors (like you) in understanding the readability of our knowledge base and reducing the difficulty of contributing to the repository. Our documentation demonstrates our commitment to clarity and efficiency, carefully constructed to ensure readability and coherence.

Repository Structure

The main directories of our repository are located within the data folder in two directories: docs and blogs. The blogs directory is our studio's announcements and a space for insightful blog writers (not influenced by external contributions).

We currently do not have plans to open the blog section for external contributions. Therefore, for now, you'll only see content from iNKORE! in the blog.

Here is the hierarchical structure of the documentation directory and the naming conventions for documents.

Category Folders

These are broad categories for grouping our content, generally named with two digits followed by a period and space, then the category name in kebab case. For example, 01. ui-elements represents the first category in the sidebar, related to user interface elements.

  • Category Metadata Files: In each category folder, the metadata files provide basic information about our structure, offering fundamental details for categorizing content. Language-specific metadata (such as display name and description) reside in language-coded files (like _category_.en-US.json).

    For more about _category_.json, see: autogenerated#category-item-metadata

Article Folders

Each article has its designated folder, represented by a two-digit number followed by a period (for manual sorting if needed), a # symbol with a space, and then the article slug in kebab case. For example, an article about button design would be nested in a folder like this: 02.# button-design. When listing controls and APIs, we prefer automatic alphabetical sorting, so you can simply write: # button-design.

Examples: index.en-US.mdx, index.zh-CN.mdx

  • Image Naming: Images in articles should be located in the same directory as index.{language_code}.mdx and named in short kebab case, such as create-a-new-project.png. The choice between PNG and JPEG formats hinges on the nature of the image – with PNG preferred for crisp, detailed images, screenshots; and JPEG suited for larger, less detailed visuals.

    Examples: create-new-project.png, mountain-view.jpg

Contribution Details

For contributors, understanding the complexity of our structure is crucial.

Writing in MDX and Markdown

The powerful features of MDX allow content to integrate with its unique features. Use Markdown to clearly articulate your ideas, emphasizing important elements with Markdown formatting to guide readers to understand the information more coherently.

We encourage the use of admonitions (a feature provided by Docusaurus) in appropriate places to provide a clear and comfortable appearance. You can refer to admonitions for more information.

Remember, use the correct heading structure for steps and other scenarios. For example, this doesn't look good:

1. Download and Install
    1.1 Install iNKORE Hub
    You can quickly and conveniently install our product using iNKORE Hub. If you haven't...

    After installing iNKORE Hub, you should have a shortcut in your Start menu that looks like this.

    1.2 Open iNKORE Hub and Download MCSkinn
    Click "iNKORE Hub" in the Programs section of your Start menu. Once initialized, click "Products" on the left panel.
    
        If any error messages pop up, you should check your settings.

2. Start Using MCSkinn
    2.1 Preparations
    Before using MCSkinn, you need a directory representing your skin library. It can be...

Instead, write like this to generate the correct directory structure:

## Step 1: Download and Install

### Install iNKORE Hub

You can quickly and conveniently install our product using iNKORE Hub. If you haven't installed iNKORE Hub on your computer yet, click the button below.

### Open iNKORE Hub and Download MCSkinn

Click "iNKORE Hub" in the Programs section of your Start menu. Once initialized, click "Products" on the left panel.
If any error messages pop up, you should check your settings.

## Step 2: Start Using MCSkinn

### Preparations

Before using MCSkinn, you need a directory representing your skin library. It can be...

Language-specific Details

Space between latin and other characters

For some language-specified documents (e.g. Chinese), it's essential to use spaces between [Chinese] and [English/letters/numbers/minor-symbols].

Always use English symbols (with exceptions)

All punctuation marks should be half-width except for commas, periods, question marks, and colons. All brackets should also be half-width, with a space on each side outside the brackets. (Slashes may not have spaces around them).

Date and Time Format

For short date, please use MM/dd/yyyy format (e.g 05/02/2024). for long date, it should be like September 20th, 2023.

For time, always follow HH:mm or HH:mm:ss rule (e.g. 16:20, 08:06:45). The military time (24-hour clock) will always be used.

The rules above applies to all documents and all locales, no matter what language the document is.

Example

For example, avoid writing like this:

2024.5.2 4:08 | 2nd May 2024 | 2024年5月2日下午4点8分
我买了34个苹果（是红的）和1只鸡【不知道是公鸡 / 还是 / 母鸡】。

Instead, write like this for better readability:

05/02/2024 16:08 | May 2nd, 2024 | 5 月 2 日 2024 年，16:08
我买了 34 个苹果 (是红的) 和 1 只鸡 [不知道是公鸡/还是/母鸡]。

Conclusion

This guide aims to provide a clear and comprehensive overview of the document structure for (potential) contributors like you. It covers naming conventions, file structure, and specific rules for writing documents.

If you have any questions, you can submit an issue on Github, join our community, or contact us directly via email. If there's anything unclear in this article, feel free to tell us or submit a Pull Request. We greatly appreciate your valuable work, which makes the documentation center better!



Yep, this document was written with the help of AI,and translated by AI again. Feel free to make translation jokes (try to keep the original meaning, don't go too far though).