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 > > >
--------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@ozone.apache.org For additional commands, e-mail: dev-h...@ozone.apache.org
