Comments (10)
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
from hwameistor.
Tasks
A task refers to the topic that can tell your how to follow steps and get a result.
from hwameistor.
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.
from hwameistor.
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.
from hwameistor.
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.
from hwameistor.
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.
from hwameistor.
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.
from hwameistor.
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.
from hwameistor.
We can refer to DaoCloud Style Guide of Writing. It is hosted on GitHub now.
from hwameistor.
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.
from hwameistor.
Related Issues (20)
- When the local-storage component is unhealthy, the status of the local storage node is still ready HOT 1
- Release Proposal v0.11.0 HOT 2
- When the local-disk-manager component is unhealthy, the status of the local disk node is still ready HOT 4
- Performing migrate after volume convert will result in missing source nodes on the UI HOT 5
- hwameistor-local-storage is displayed as Running, but the status of local-storage-csi-controller is actually CrashLoopBackOff HOT 4
- hwameistor-local-disk-manager is displayed as Running, but the status of local-disk-csi-controller is actually CrashLoopBackOff HOT 2
- DRDB should support redhat 8.4 and add e2e test HOT 2
- check kubecost efficiency, should meet the criteria
- 磁盘预留需求 HOT 1
- CNCF Sandbox onboarding HOT 4
- Can pods with HA pv migrate to other nodes successfully when the primary replicas node is down ? HOT 4
- The environment has cgroup2 installed, resulting in the failure to create data volumes normally HOT 1
- [doc]The Chinese documentation of Volume Provisioned IO has content duplication HOT 1
- StorageClass with the maximum IOPS and throughput parameters cannot be used normally HOT 5
- [doc]Some Chinese documents use English HOT 1
- Release Proposal v0.11.1 HOT 2
- In the Chinese document, the LDC that needs to be issued in “ Disk Expansion ” lacks the owner
- How hwameistor specify raw disk data volume? HOT 22
- When the reclaimPolicy of sc is Retain, the lv will not be deleted when the PV is deleted HOT 2
- [Feature Request] Add creation timestamp when expand storage node HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from hwameistor.