Hello Ozone Community, As many of you are aware, Ozone's website and documentation has remained somewhat disorganized and lacking in content for a while. I would like to kick start an initiative to change that. I have attached a document outlining a plan to redo Ozone's website and documentation so that it will not be a barrier for new adopters and can be easily updated to hold all content we wish to publish. The document outlines a high level plan that will be broken into multiple parent jiras with subtasks to follow while the new website is under construction. I would encourage everyone to read it and give feedback on this initiative. I also presented this content in this week's U.S time zone community sync.
As part of "Phase 1" in the document, I would like to make the following proposals: 1. Migrate Ozone's static site generator from Hugo to Docusaurus. Docusaurus <https://docusaurus.io/> is an MIT licensed static site generator maintained by Meta/Facebook open source. While there are many examples <https://docusaurus.io/showcase> of sites using Docusaurus, including the Docusaurus site itself, YuniKorn <https://yunikorn.apache.org/> is another Apache project that is successfully using the framework for their website. I have discussed this with two Yunikorn PMC members who work on the site and they said the experience has been positive. What does Docusaurus provide us that Hugo does not? Hugo's advantage is that it is written in Go, so in theory the site can be built from just one easy to install binary. Docusaurus is written in Javascript, so it needs to be installed from a package manager like npm. However, if we want to make the site more robust with things like collapsable menus, minimap side bar, header linking, search, breadcrumbs, and more, we would probably need to depend on a Hugo theme rather than build all these things from scratch. Hugo themes with these features, like Doks <https://getdoks.org>, are also javascript packages that require node to build, but have the following disadvantages: - Configuration becomes split between the theme and Hugo itself. It is not intuitive for new developers whether a config belongs to Hugo or the theme, or whose documentation to read to make changes. - The site is now highly dependent on another library that may not get the same amount of updates or support as the main Hugo project. Since Docusaurus is built specifically for project documentation, it provides all these features with its default theme, and configuration happens in a centralized docusaurus.config.js file. I have tested it and can confirm that it is just as easy to spin up the site locally and view edits in real time as Hugo. It also has a built in versioning <https://docusaurus.io/docs/versioning> framework that we can use instead of our manual process of copying over docs from the main Ozone repo, which brings me to my next proposal. 2. Move our docs out of the ozone repo and into the ozone-site repo. In theory, having docs tracked and versioned in the same repo as the code sounds like a good idea, but in practice, we do not use any of the potential benefits: - We always use separate PRs to update docs and code, and I think this actually makes reviews easier. - The existence of the docs in the same repo as the code does not seem to "remind" anyone to update the docs if something relevant changes. Zita suggested at the community sync that adding a reminder to update docs to our PR template would probably be more effective. - Relations between code and doc changes can already be created with existing Jira and Github linking features, even across repos. This split model does cause us problems: - It is challenging to automatically publish incremental updates to the versioned portion of the docs. In order to update the versioned docs, we need to build the docs within Ozone, and manually copy the built artifacts into the asf-site branch of the ozone-site repo. This is a confusing process, since most doc updates to ozone-site are supposed to happen on the master branch which is automatically built into the asf-site branch. Because of this, content updates to our docs are rarely published outside of a release, even if they are committed earlier. - The most up to date docs are built from the ozone master branch and must live on a separate site <https://ci-hadoop.apache.org/view/Hadoop%20Ozone/job/ozone-doc-master/lastSuccessfulBuild/artifact/hadoop-hdds/docs/public/index.html> from ozone.apache.org because there is no integration between the main ozone repo and the automatic doc publishing in the ozone-site repo. - We must manually version our documentation instead of letting our site generator do it for us. This can be error prone. For example, see the comments on the 1.3.0 doc update PR <https://github.com/apache/ozone-site/pull/28>. For these reasons, I propose moving the docs out of the main Ozone repo and into the ozone-site repo. Work on the improved website and docs can happen on a branch in the ozone-site repo until it is ready to be published. The attached document outlines a detailed and incremental plan to push Ozone's website and documentation to its full potential. Please review the plan and let me know your thoughts. I plan for this to be my primary project for the next few months, with the goal of getting the new site to a publishable state by the end of this year. A few other engineers at Cloudera have agreed to help part time, but we would greatly appreciate help from the open source community of developers and users as we work on this. Even if you do not have the time or ability to contribute content, reviews from a wide audience will improve the quality of the new site and docs. Thanks, Ethan
--------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@ozone.apache.org For additional commands, e-mail: dev-h...@ozone.apache.org
