+1 , this is a much needed improvement.
Thanks, Dinesh On Mon, Aug 28, 2023 at 8: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
