Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve language in docs & product #341

Closed
liujiajun opened this issue Jan 9, 2022 · 1 comment
Closed

Improve language in docs & product #341

liujiajun opened this issue Jan 9, 2022 · 1 comment
Labels
enhancement New feature or request

Comments

@liujiajun
Copy link

liujiajun commented Jan 9, 2022

I love the product. However, the language in docs & product is sometimes awkward and/or contains grammar mistakes. While it does not affect understanding, I believe it is something that can be improved upon.

Some examples are:

  • It is not clear to me why three tenses are used here ("bookkeeping", "scan", & "detects")

Screen Shot 2022-01-09 at 11 35 21 AM

  • Is "project" countable? The usage is not consistent between the first sentence and the second and third. Also, A "project" is not comparable with a "project concept".

Screen Shot 2022-01-09 at 11 38 39 AM

I think the accumulation of details like these could affect how the product is overall perceived. Adding a dedicated writing style guide could be helpful (like the Apple Publications Style Guide).

@liujiajun liujiajun added the enhancement New feature or request label Jan 9, 2022
tianzhou added a commit to bytebase/bytebase.com-old that referenced this issue Jan 9, 2022
@tianzhou
Copy link
Collaborator

tianzhou commented Jan 9, 2022

Thanks for raising this. The first problem is an unfortunate, we just updated the website.

Bytebase project is similar to the project concept in other common dev tools.

This was intended, another way to write is "The Bytebase project concept is similar to the project concept in other common dev tools." However, that is less terse.

Adding a dedicated writing style guide could be helpful (like the Apple Publications Style Guide).

We are always aspiring to great technical writing.

For Bytebase, we just started to build the technical writing guideline (we did include Apple's document as a primary reference. There is still a long way to go.

Please feel free to raise issues if you find more issues.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants