[Improvement][Doc] Fix typos, tense, formatting, letter case, etc. errors in docs

apache / dolphinscheduler

Apache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code

https://dolphinscheduler.apache.org/

Apache License 2.0

12.87k stars 4.63k forks source link

[Improvement][Doc] Fix typos, tense, formatting, letter case, etc. errors in docs #11385

Closed EricGao888 closed 4 months ago

EricGao888 commented 2 years ago

Search before asking

[X] I had searched in the issues and found no similar feature requirement.

Description

Currently our English doc quality is not so good:

We have tons of tense, formatting, punctuation, etc. errors and inconsistency of letter case usage in docs.
Some sentences are ambiguous, misleading or hard to understand.
We need to avoid passive voice in doc writing.
Markdown docs are badly formatted.

Since @zhongjiajie has already migrated all docs from website repo to main repo, and we have spotless to help with the markdown formatting #11384, it's high time that we refactored the docs.

Besides, we need a guideline for DS English docs writing, see: #11161

related: #6535

Are you willing to submit a PR?

[X] Yes I am willing to submit a PR!

Code of Conduct

[X] I agree to follow this project's Code of Conduct

github-actions[bot] commented 2 years ago

Thank you for your feedback, we have received your issue, Please wait patiently for a reply.

In order for us to understand your request as soon as possible, please provide detailed information、version or pictures.
If you haven't received a reply for a long time, you can join our slack and send your question to channel #troubleshooting

zhongjiajie commented 2 years ago

We have tons of tense, formatting, punctuation, etc. errors and inconsistency of letter case usage in docs.

I think we better find some way to auto-fix those issues,

Markdown docs are badly formatted

I am not sure how spotless auto-fix this, but I am sure there are some of the docs can not be auto fix, like we have HTML style IMG format, beside the auto-fix tool, maybe we also need a checker for our markdown doc and other CI which I already mention in #6535

EricGao888 commented 2 years ago

We have tons of tense, formatting, punctuation, etc. errors and inconsistency of letter case usage in docs.

I think we better find some way to auto-fix those issues,

Markdown docs are badly formatted

I am not sure how spotless auto-fix this, but I am sure there are some of the docs can not be auto fix, like we have HTML style IMG format, beside the auto-fix tool, maybe we also need a checker for our markdown doc and other CI which I already mention in #6535

@zhongjiajie Thanks for the information, I will take a look at the doc checker you mentioned above : )

EricGao888 commented 2 years ago

We have tons of tense, formatting, punctuation, etc. errors and inconsistency of letter case usage in docs.

I think we better find some way to auto-fix those issues,

Markdown docs are badly formatted

I am not sure how spotless auto-fix this, but I am sure there are some of the docs can not be auto fix, like we have HTML style IMG format, beside the auto-fix tool, maybe we also need a checker for our markdown doc and other CI which I already mention in #6535

BTW, spotless fixes markdown using Flexmark.

zhongjiajie commented 2 years ago

I like this feature, like the auto-fix behavior, but I think we should find out all bad case formats too. I think the second is even more important

EricGao888 commented 2 years ago

I like this feature, like the auto-fix behavior, but I think we should find out all bad case formats too. I think the second is even more important

Agree, it would be better if those embedded stuff in markdown such as html code fragments could be fixed or at least get checked.

EricGao888 commented 2 years ago

I like this feature, like the auto-fix behavior, but I think we should find out all bad case formats too. I think the second is even more important

@zhongjiajie Just for clarification, for tense, formatting, punctuation, etc. errors and inconsistency of letter case usage, I will fix them manually, there is no way for fixing those stuff automatically. Only use spotless for markdown formatting.

zhongjiajie commented 2 years ago

I like this feature, like the auto-fix behavior, but I think we should find out all bad case formats too. I think the second is even more important

@zhongjiajie Just for clarification, for tense, formatting, punctuation, etc. errors and inconsistency of letter case usage, I will fix them manually, there is no way for fixing those stuff automatically. Only use spotless for markdown formatting.

Yeah, Of cause , but other things like a blank line, HTML syntax img, max cols in each line should be auto-fix if it can

github-actions[bot] commented 2 years ago

This issue has been automatically marked as stale because it has not had recent activity for 30 days. It will be closed in next 7 days if no further activity occurs.

github-actions[bot] commented 2 years ago

This issue has been closed because it has not received response for too long time. You could reopen it if you encountered similar problems in the future.