In addition to layout revamp, one thing I'd love to see is more user docs. Our doc is by and large written for core Ozone developers. We need to have more content around how to run workarounds, how to migrate existing applications from HDFS to Ozone, API guide ... etc.
On Mon, Aug 28, 2023 at 5:25 PM Ethan Rose <er...@cloudera.com.invalid> wrote: > 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
