Skip to content

HDDS-13396. Documentation: Improve the top-level overview page for new users. #8753

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.

Sign up for GitHub

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

Jump to bottom
Merged
jojochuang merged 4 commits into from
Jul 23, 2025
Merged

HDDS-13396. Documentation: Improve the top-level overview page for new users. #8753

jojochuang merged 4 commits into from
Jul 23, 2025

Conversation

@jojochuang
Copy link
Contributor

@jojochuang jojochuang commented Jul 6, 2025

What changes were proposed in this pull request?

HDDS-13396. Documentation: Improve the top-level overview page for new users.

Please describe your PR in detail:

  • The previous overview page was technically accurate but could be intimidating for newcomers. This change revamps the page to be more welcoming and informative by:
  • Providing a clear, benefit-oriented introduction.
  • Adding a comparison table to HDFS and S3 for better context.
  • Highlighting a single, recommended quick-start path (Docker).
  • Listing concrete use cases to illustrate practical applications.
  • Generated-by: Google Gemini Pro 2.5 + Gemini Cli, Prompt:

Read all the user documents for me (under /hadoop-hdds/docs/content), digest it, and tell me: do you think you have a good grasp of what Ozone is? What is missing that you think would be good to have?
What else would you think should be added, from the perspective of someone with no idea what Ozone is?
Based on your observations, what should the topmost Overview page look like? Update the page based on your recommendation.

Tokens used:


│  Input Tokens             1,652,832  │
│  Output Tokens                7,301  │
│  Thoughts Tokens              5,376  │
│  ──────────────────────────────────  │
│  Total Tokens             1,665,509  │
│                                      │
│  Total duration (API)            3m  │

What is the link to the Apache JIRA

https://issues.apache.org/jira/browse/HDDS-13396

How was this patch tested?

Draft prepared by Gemini, reviewed and updated manually.

@jojochuang
HDDS-13396. Documentation: Improve the top-level overview page for ne…
2cc1267 
…w users.

The previous overview page was technically accurate but could be
intimidating for newcomers. This change revamps the page to be more
welcoming and informative by:

- Providing a clear, benefit-oriented introduction.
- Adding a comparison table to HDFS and S3 for better context.
- Highlighting a single, recommended quick-start path (Docker).
- Listing concrete use cases to illustrate practical applications.

Change-Id: Id7e9d5db7415e043d2a7ea33de6fd9afea21b932
@jojochuang jojochuang added documentation Improvements or additions to documentation AI-gen labels Jul 6, 2025
@kerneltime
Copy link
Contributor

kerneltime commented Jul 7, 2025

I think the content on this page is a bit more detailed, do you want to merge the two? https://kerneltime.github.io/ozone-site/docs/

@jojochuang
Backport Overview page from v2 site.
663ac4b 
Change-Id: Ia5979b1cbc73131d430c2c00d1a3721d792d348b
@jojochuang
Copy link
Contributor Author

jojochuang commented Jul 7, 2025

Good idea. I'll just backport the Overview page from the v2 site.

@ivandika3 ivandika3 requested a review from kerneltime July 10, 2025 04:03
Tejaskriya
Tejaskriya reviewed Jul 14, 2025
View reviewed changes
Copy link
Contributor

@Tejaskriya Tejaskriya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this contribution @jojochuang , Faced an issue when I checked the patch locally, could you please check the below?

hadoop-hdds/docs/content/_index.md Outdated
Comment on lines 115 to 119
* **New to Ozone?** Try the **[Quick Start Guide](./02-quick-start/README.mdx)** to set up a cluster.
* **Want to understand the internals?** Read about the **[Core Concepts](./03-core-concepts/README.mdx)** (architecture, replication, security).
* **Need to use Ozone?** Check the **[User Guide](./04-user-guide/README.mdx)** for client interfaces and integrations.
* **Managing a cluster?** Consult the **[Administrator Guide](./05-administrator-guide/README.mdx)** for installation, configuration, and operations.
* **Running into issues?** The **[Troubleshooting Guide](./06-troubleshooting/README.mdx)** may provide assistance.
Copy link
Contributor

@Tejaskriya Tejaskriya Jul 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When I checked with a hugo serve, these links didn't lead to anywhere, with a "Page not found" error.
Maybe the reference paths need to be in the format used in your other pr?

Copy link
Contributor Author

@jojochuang jojochuang Jul 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Pushed an update.

@jojochuang
docs(hdds): Fix broken links in Dive Deeper section
19ee2a2 
Change-Id: I2cf096c49648f90c5f3bacf528c91a295f77c921
@jojochuang jojochuang requested a review from Tejaskriya July 14, 2025 18:30
Tejaskriya
Tejaskriya reviewed Jul 15, 2025
View reviewed changes
@jojochuang @Tejaskriya
Update hadoop-hdds/docs/content/_index.md
b805973 
Co-authored-by: Tejaskriya <87555809+Tejaskriya@users.noreply.github.com>
@jojochuang
Copy link
Contributor Author

jojochuang commented Jul 15, 2025

Thanks @Tejaskriya it was working for me though. But your update is more idiomatic so I'll take it!

@jojochuang jojochuang requested a review from Tejaskriya July 22, 2025 00:18
Tejaskriya
Tejaskriya approved these changes Jul 23, 2025
View reviewed changes
Copy link
Contributor

@Tejaskriya Tejaskriya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for considering my suggestion, LGTM!

@jojochuang jojochuang merged commit 3cebcc9 into apache:master Jul 23, 2025
14 checks passed
@jojochuang
Copy link
Contributor Author

jojochuang commented Jul 23, 2025

Thanks @Tejaskriya and @kerneltime

@jojochuang
Copy link
Contributor Author

jojochuang commented Jul 23, 2025

Missed the "Generated-by: Google Gemini Pro 2.5 + Gemini Cli" message in the commit

errose28 added a commit to errose28/ozone that referenced this pull request Jul 30, 2025
@errose28
Merge branch 'master' into HDDS-12078-improve-cli
4a2347c 
* master: (730 commits)
  HDDS-13083. Handle cases where block deletion generates tree file before scanner (apache#8565)
  HDDS-12982. Reduce log level for snapshot validation failure (apache#8851)
  HDDS-13396. Documentation: Improve the top-level overview page for new users. (apache#8753)
  HDDS-13176. containerIds table value format change to proto from string (apache#8589)
  HDDS-13449. Incorrect Interrupt Handling for DirectoryDeletingService and KeyDeletingService (apache#8817)
  HDDS-2453. Add Freon tests for S3 MPU Keys (apache#8803)
  HDDS-13237. Container data checksum should contain block IDs. (apache#8773)
  HDDS-13489. Fix SCMBlockdeleting unnecessary iteration in corner case. (apache#8847)
  HDDS-13464. Make ozone.snapshot.filtering.service.interval reconfigurable (apache#8825)
  HDDS-13473. Amend validation for OZONE_OM_SNAPSHOT_DB_MAX_OPEN_FILES (apache#8829)
  HDDS-13435. Add an OzoneManagerAuthorizer interface (apache#8840)
  HDDS-8565. Recon memory leak in NSSummary (apache#8823).
  HDDS-12852. Implement a sliding window counter utility (apache#8498)
  HDDS-12000. Add unit test for RatisContainerSafeModeRule and ECContainerSafeModeRule (apache#8801)
  HDDS-13092. Container scanner should trigger volume scan when marking a container unhealthy (apache#8603)
  HDDS-13070. OM Follower changes to create and place sst files from hardlink file. (apache#8761)
  HDDS-13482. Mark testWriteStateMachineDataIdempotencyWithClosedContainer as flaky
  HDDS-13481. Fix success latency metric in SCM panels of deletion grafana dashboard (apache#8835)
  HDDS-13468. Update default value of ozone.scm.ha.dbtransactionbuffer.flush.interval. (apache#8834)
  HDDS-13410. Control block deletion for each DN from SCM. (apache#8767)
  ...

hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/scm/container/ContainerReplicaInfo.java
hadoop-ozone/cli-admin/src/main/java/org/apache/hadoop/hdds/scm/cli/container/ReconcileSubcommand.java
hadoop-ozone/cli-admin/src/test/java/org/apache/hadoop/hdds/scm/cli/container/TestReconcileSubcommand.java
jojochuang added a commit to jojochuang/ozone that referenced this pull request Jul 31, 2025
@jojochuang @Tejaskriya
HDDS-13396. Documentation: Improve the top-level overview page for ne…
5b80870 
…w users. (apache#8753)

Co-authored-by: Tejaskriya <87555809+Tejaskriya@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Tejaskriya Tejaskriya Tejaskriya approved these changes

@peterxcli peterxcli Awaiting requested review from peterxcli

@chungen0126 chungen0126 Awaiting requested review from chungen0126

@kerneltime kerneltime Awaiting requested review from kerneltime

Assignees

No one assigned

Labels

AI-gen documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jojochuang @kerneltime @Tejaskriya