mirror of
https://github.com/kubesphere/website.git
synced 2025-12-26 00:12:48 +00:00
Update doc style guide
Signed-off-by: Sherlock113 <sherlockxu@yunify.com>
This commit is contained in:
parent
1838d6daf6
commit
a674c8eb39
|
|
@ -43,6 +43,10 @@ Give a title first before you write a paragraph. It can be grouped into differen
|
|||
|
||||
When you submit your md files to GitHub, make sure you add related image files that appear in md files in the pull request as well. Please save your image files in static/images/docs. You can create a folder in the directory to save your images.
|
||||
|
||||
If you want to add remarks (e.g. put a box on a UI button), use the color **green**. As some screenshot apps does not support the color picking function for a specific color code, as long as the color is **similar** to #09F709, #00FF00, #09F709 or #09F738, it is acceptable.
|
||||
|
||||
Recommended: [Xnip](https://xnipapp.com/) for Mac and [Sniptool](https://www.reasyze.com/sniptool/) for Windows.
|
||||
|
||||
## Tone
|
||||
|
||||
- Do not use “we”. Address the reader as “you” directly. Using “we” in a sentence can be confusing, because the reader might not know whether they are part of the “we” you are describing. You can also use words like users, developers, administrators and engineers, depending on the feature you are describing.
|
||||
|
|
@ -66,7 +70,8 @@ Use a **period** or a **conjunction** between two **complete** sentences.
|
|||
|
||||
### **Bold**
|
||||
|
||||
Mark any UI text (e.g. a button) in bold.
|
||||
- Mark any UI text (e.g. a button) in bold.
|
||||
|
||||
|
||||
| Do | Don't |
|
||||
| ------------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
|
|
@ -74,15 +79,21 @@ Mark any UI text (e.g. a button) in bold.
|
|||
| In **Workspaces**, you can see all your workspaces listed. | In Workspaces, you can see all your workspaces listed. |
|
||||
| On the **Create Project** Page, click **OK** in the bottom-right corner to continue. | On the Create Project Page, click OK in the bottom-right corner to continue. |
|
||||
|
||||
- Mark the content of great importance or deserving special attention to readers in bold. For example:
|
||||
|
||||
KubeSphere is a **distributed operating system managing cloud-native applications** with Kubernetes as its kernel.
|
||||
|
||||
### **Code**
|
||||
|
||||
For short commands, you can just put them within ``.
|
||||
- For short commands, you can just put them within ``. This is often used when you only need to tell readers about a short command or it is sufficient to express your meaning just with the command in a sentence.
|
||||
|
||||
|
||||
| Do | Don't |
|
||||
| ------------------------------------------------- | ----------------------------------------------- |
|
||||
| You can use `kubectl get pods` to list your pods. | You can use kubectl get pods to list your pods. |
|
||||
|
||||
Alternatively, you can use code fences so that readers can copy them directly, especially for long commands. For example:
|
||||
- Alternatively, you can use code fences so that readers can copy them directly, especially for long commands. For example:
|
||||
|
||||
|
||||
Execute the following command to edit the configuration of `ks-console`:
|
||||
|
||||
|
|
@ -90,6 +101,53 @@ Execute the following command to edit the configuration of `ks-console`:
|
|||
kubectl edit svc ks-console -o yaml -n kubesphere-system
|
||||
```
|
||||
|
||||
- For values, strings, fields or parameters in yaml files, put them within ``.
|
||||
|
||||
| Do | Don't |
|
||||
| ------------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| Change the value of `auditing.enabled` to `false` to stop receiving auditing logs from KubeSphere. | Change the value of auditing.enabled to false to stop receiving auditing logs from KubeSphere. |
|
||||
|
||||
- Put all path and file names within ``.
|
||||
|
||||
However, if the file name itself contains a link, do not put it within ``.
|
||||
|
||||
| Do | Don't |
|
||||
| -------------------------- | ------------------------ |
|
||||
| `/root/csi-qingcloud.yaml` | /root/csi-qingcloud.yaml |
|
||||
| `config-sample.yaml` | config-sample.yaml |
|
||||
| `/var/lib/docker` | /var/lib/docker |
|
||||
|
||||
- Put account names or role names within ``.
|
||||
|
||||
| Do | Don't |
|
||||
| ------------------------------------------------------ | ---------------------------------------------------- |
|
||||
| Log in the console as `admin`. | Log in the console as admin. |
|
||||
| The account will be assigned the role `users-manager`. | The account will be assigned the role users-manager. |
|
||||
|
||||
### Code Comments
|
||||
|
||||
- If the comment is used only for a specific value, put the comment on the same line of the code. However, if the code is too long and putting the comment on the same line is not appropriate in terms of reading experience, you can put the code comment above the code. For example:
|
||||
|
||||
```yaml
|
||||
registry:
|
||||
registryMirrors: [] # For users who need to speed up downloads.
|
||||
```
|
||||
|
||||
```bash
|
||||
# Assume your original Kubernetes cluster is v1.17.9
|
||||
./kk create config --with-kubesphere --with-kubernetes v1.17.9
|
||||
```
|
||||
|
||||
- If the comment is used for all the code (e.g. serving as a header for explanations), put the comment at the beginning above the code. For example:
|
||||
|
||||
```yaml
|
||||
# Internal LB config example
|
||||
controlPlaneEndpoint:
|
||||
domain: lb.kubesphere.local
|
||||
address: "192.168.0.253"
|
||||
port: "6443"
|
||||
```
|
||||
|
||||
## Links
|
||||
|
||||
**Internal Links**
|
||||
|
|
|
|||
Loading…
Reference in New Issue