tengqm commented on code in PR #5840:
URL: https://github.com/apache/gravitino/pull/5840#discussion_r1881158655
##########
docs/cli.md:
##########
@@ -8,25 +8,29 @@ last_update:
license: 'This software is licensed under the Apache License version 2.'
---
-This document provides guidance on managing metadata within Apache Gravitino
using the Command Line Interface (CLI). The CLI offers a terminal based
alternative to using code or the REST interface for metadata management.
+This document provides a guidance on managing metadata within Apache Gravitino
using
+the Command Line Interface (CLI). The CLI offers a terminal based alternative
to
+using code or the REST API for metadata management.
Review Comment:
Em... Let me try articulate the reasons behind this kind of changes.
- We'd better treat docs as code. That means we write them and then track
whatever
changes in the future.
- The GIT tool compare changes on a line by line basis. When we have a long
line of
text, GIT can only tell you that this "line" has changed. We as human
reviewers have
to identify the actual change(s) manually. That means a painful experience
like finding
a needle fallen on the ground.
- The GitHub web UI works the same way. I have myself been tortured by this
for many years.
- When we break long lines manually, appropriately, this line breaks are not
impacting
the rendered output (mainly HTML here).
- With manual line breaks, we ensure that every developer sees the same
thing on his
or her environment. Think about the tab size problem here.
- I am not quite sure how an IDE helps improve the documentation. Even if
there is an
IDE (say IDEA) can do a great job for something, we are not writing
code/docs for
that IDE. Human is not supposed to be hijacked by tools, right?
- I'm open to learn the draw backs of manually wrapped long lines. In some
other
communities, manually wrapping long lines is strongly encouraged.
- This does NOT mean we want to encourage people to break the long lines at
a fix boundary.
The recommended way is to break them WHEN APPROPRIATE. For example, we
encourage
breaking long lines when a statement ends, when there is a punctuation
character,
so on and so forth. We discourage breaking links, however, because it
doesn't make
a lot of senses.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
