You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Next »

Proposers

Approvers

Status

Current state: Under Discussion

Discussion thread: here

JIRA: here

Released: <Hudi Version>

Abstract

This RFC aims at improving the Hudi web documentation for users and the process of updating docs for developers.

Background

There are a few gaps we observed regarding the docs:

  • We only have one version of docs kept at the asf-site branch for the latest release.  Given that each version has new features and improvements, some involving configuration and parameter changes compared to to previous versions, the single version of docs can create confusion for users using a previous release of Hudi.
  • There's no API docs generated from the code.
  • Current process of building, testing, and deploying docs (i.e the content powering hudi.apache.org) is mostly manual.

Implementation

To address these gaps, restructuring of the docs is needed to make the process easier.  The diagram below shows the structuring and the workflow.

Versioning docs


The release-specific documentation (release docs) should evolve with the code changes.  Thus, maintaining the docs regarding design, implementation details and API examples on master under /docs would make things easier.  In this way, the code and the corresponding docs change can coexist in the same PR.  Specific pages around these include:

  • Quickstart
  • Concepts
  • Writing Data
  • Querying Data
  • Configuration
  • Performance
  • Administering

In addition to these content, a new set of API docs will be generated by javadoc for each release (similar to this).

Content regarding the general information of Hudi should remain in asf-site branch (site docs):

  • Use Cases
  • Talks & Powered By
  • Comparison
  • Releases
  • Community
  • Code
  • Developers
  • Feedback

The release docs on master and site docs in asf-site are generated separately.  The generated web pages are then uploaded to the hosting server for the Hudi site.  The landing page references the specific version of docs content through links.

For backward compatibility, we can manually generate the content for current (0.5.0-incubating) and one or two old releases (0.4.6/0.4.7), to fit into the new docs structure. 

Automating docs update

To make updating and deploying docs content easier, a set of scripts automating the above process will be added.  In this way, once the changes to the /docs on either master or asf-site are landed, the update content pages can be uploaded to the hosting server of Hudi website.  The API docs on master branch is also going to be maintained in this way.

Rollout/Adoption Plan

  • No impact on existing users regarding APIs as this is docs website change.

Test Plan

  • Test the content organization locally to make sure the links are working and the content is readable

Appendix

  • Improvements and discussion on the content of the landing page are moved here


  • No labels