I cannot seem to send the doc on this email thread, sorry for the confusion. I have instead filed HDDS-9225 <https://issues.apache.org/jira/browse/HDDS-9225> as a parent Jira for this task and attached the doc there. The link is here <https://issues.apache.org/jira/secure/attachment/13062569/Improving%20the%20Apache%20Ozone%20Website.pdf> as well. The proposal includes details for improving both the site layout and its content.
Ethan On Tue, Aug 29, 2023 at 11:17 AM Ethan Rose <er...@cloudera.com> wrote: > Thanks for the responses, it seems the PDF document did not attach > correctly. I have re-attached it to this email. If it is still not visible > I will post it on Jira and share the link. > > Ethan > > On Tue, Aug 29, 2023 at 1:45 AM Zita Dombi <zitado...@apache.org> wrote: > >> +1, this is a really good idea, I think many people will benefit from it. >> I >> started working on Ozone freshly graduated, as my first job, so I felt the >> disadvantages of the current website and documentation while learning >> about >> Ozone. The document you shared on the community sync is very detailed, you >> also mentioned that you attached it in the email above, but I can't find >> it >> there, maybe I'm missing something :) >> >> thanks, >> Zita >> >> Dinesh Chitlangia <dine...@apache.org> ezt írta (időpont: 2023. aug. 29., >> K, 4:44): >> >> > +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 >> > >> >
