[docs] Added a style guide

[windsonsea]

HwameiStor documentation has three different topics currently. It is recommended to provide a simple style guide if more than 20 topics in a docsite.

• Concept
• Task (steps)
• Reference

References:

• Kubernetes Style Guide
• Simple English Writing Style Guide

[windsonsea]

Images and Code

It is always welcome if you can output some diagrams about architecture, modules, principle, features desc, etc.

A useful picture is worth of a thousand words.

However, some images are not suggested, or even to avoid. For example, in a long blog, when you run a simple command and the system outputs something on your screen. In this case, it's better to directly copy/paste your on-screen text rather than a screenshot as below.

As shown above, it's difficult to control the resolution and pixels of an image to adapt to different hardware and cloud environment, and not easy to reproduce your dev, test, use environment. Few people may follow your screenshot to type the command letter by letter again because the reader cannot view it clearly!

What is a good way to show your code and output?

For a code snippet, you need to provide some properties:

• Show clearly
• Easy to read
• Easy to copy/paste
• Give some comments if possible
• Give highlights with the label of c, c++, yaml, java, shell, bash, or go if you know.

apiVersion: batch/v1
kind: Job
metadata:
  name: hello
spec:
  template:
    # This is the pod template
    spec:
      containers:
      - name: hello
        image: busybox:1.28
        command: ['sh', '-c', 'echo "Hello, Kubernetes!" && sleep 3600']
      restartPolicy: OnFailure
    # The pod template ends here

[windsonsea]

Tasks

A task refers to the topic that can tell your how to follow steps and get a result.

[windsonsea]

Reference

A reference page may list many commands, flags, options, APIs, and more. When a user doesn't remember something, he/she will come to search for.

[windsonsea]

Concepts

A concept describes what, when, why, where, and more. It will be a good topic of concept if you can add sufficient diagrams, examples, and reference links in addition to a clear and clean text desc.

[windsonsea]

Test Report

A test report shall provide what is bad, not good, or weakness in addition to everything good. Sometimes, complaints are more useful than curry favor. We are technical-related!

Your sincerity can tell readers that you are striving to do something. If you tell everyone that everything is always good enough, though not that case in fact, no any response, and no real growth, the community is close to dead in reality.

The value of a test report is to find bugs, incompatibility issues, gaps, and more weaknesses, so these issues can be reflected in your roadmap and assigned to your dev job list.

[windsonsea]

What Is a Solution?

A solution refers to combine different features into a package to deal with a scenario, and try to make a trouble easy.

In a solution, you should provide clear procedures, required features and components, and relevant resources. Tell your reader what the scenario is or what the requisites are. A solution has the feature of reproduction if you encounter the similar situation later.

[sun7927]

Can we add an auto-checker for the style of the document?

I strongly suggest to draft a wiki page for this style guide instead. I don't think "issue" is the good place to have it.

[github-actions]

This issue has been marked as stale because it has been open for 90 days with no activity. This thread will be automatically closed in 30 days if no further activity occurs.

[windsonsea]

We can refer to DaoCloud Style Guide of Writing. It is hosted on GitHub now.

[github-actions]

This issue has been marked as stale because it has been open for 90 days with no activity. This thread will be automatically closed in 30 days if no further activity occurs.