markhoerth commented on PR #12399: URL: https://github.com/apache/gravitino/pull/12399#issuecomment-5245893994
@yuqi1129 thank you, and you are right about the defect. Pushed a revision that addresses it. **On `how-to-use-gvfs.md`, you are correct and it was a real bug.** That page had two sections whose entire content was links into the pages this PR deletes, one for the Java client and one for Python. A site build against the branch reported eight broken links from that file alone. Both sections now carry the cloud configuration themselves: a property table per storage backend, a worked example, and the `s3_endpoint` asymmetry preserved, since it is optional for the Python client and required for Java. The generic document no longer depends on pages that are going away. **On the end-to-end journey, I think we were closer than the diff made it look.** `how-to-use-gvfs.md` already carried complete runnable examples for the Hadoop command line, Java, Spark, TensorFlow, the fsspec interface, and pandas. What it was missing was the backend-specific configuration, which is exactly the gap you identified. With that filled in, the full path works for every backend. **`fileset-catalog.md` now opens with a Quick Start** running catalog, schema, fileset, and access, which the page did not have before. It closes by saying that only the first step changes per backend, so a reader picking a cloud can follow that page start to finish and then follow the GVFS page start to finish, with no inference required about jars, credentials, or configuration. **Where I would push back is on volume being free.** It is not, and the cost falls on the newcomer rather than on us. A reader arriving at the fileset section met eight pages and 3,117 lines. Five of them carried the same twenty headings in the same order, and after normalizing the cloud name, 70 to 83 percent of each was byte-identical to the S3 page. That reader cannot tell which page applies to them without opening several, and once inside one they cannot tell which paragraphs are specific to their cloud and which are boilerplate they could have read anywhere. The part that actually differs is three credential properties and a bundle jar. It is sitting in 600 lines of material that is the same everywhere. The effect is that filesets look harder than they are. Someone evaluating Gravitino sees a wall of documentation and concludes the feature is complicated, when the real answer for their cloud is a handful of properties. Self-containedness is genuinely valuable, and I am not arguing against it. But a page a reader cannot find, or cannot skim once found, is not serving them either. Two complete pages are easier to get started from than five near-identical ones, and that is the trade I was making. If the runnable path still reads as thin after this revision, tell me where specifically and I will fill it in. I would rather close the gap than restore the copies. Mark -- 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]
