+1 for the documentation. I have been lurking on this project waiting for the opportunity to contribute to the documentation.
Thanks for the great start Ethan. [cid:image001.png@01D9DA7F.B27341E0]<https://www.veteransunited.com/> Eric Brown Applications Administrator 573-876-2600 ext 7946<tel:573-876-2600,7946> 550 Veterans United Drive | Columbia, MO 65201 eric.br...@vu.com<mailto:eric.br...@vu.com> | VeteransUnited.com<https://www.veteransunited.com/> From: Ethan Rose <er...@cloudera.com.INVALID> Sent: Tuesday, August 29, 2023 1:17 PM To: dev@ozone.apache.org Subject: [EXT] Re: Improving the Apache Ozone Website and Documentation 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 <zitadombi@ apache. org> 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<mailto: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<mailto: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<mailto: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/ > > [docusaurus.io]<https://urldefense.com/v3/__https:/docusaurus.io/__;!!HL9eAG-pe8ETeg!ZrMzG75stPrzIflnRbVqP3_kLlLaKRPPBXkFvHRbyOowNqu0ieXWdtfqpQU9tgXWfBFaDlLROFXEOVDzQEMkRrnAylPR$>> > > is an MIT licensed static site > > generator maintained by Meta/Facebook open source. While there are many > > examples <https://docusaurus.io/showcase > > [docusaurus.io]<https://urldefense.com/v3/__https:/docusaurus.io/showcase__;!!HL9eAG-pe8ETeg!ZrMzG75stPrzIflnRbVqP3_kLlLaKRPPBXkFvHRbyOowNqu0ieXWdtfqpQU9tgXWfBFaDlLROFXEOVDzQEMkRoQJu0xE$>> > > of sites using Docusaurus, > > including the Docusaurus site itself, YuniKorn > > <https://yunikorn.apache.org/ > > [yunikorn.apache.org]<https://urldefense.com/v3/__https:/yunikorn.apache.org/__;!!HL9eAG-pe8ETeg!ZrMzG75stPrzIflnRbVqP3_kLlLaKRPPBXkFvHRbyOowNqu0ieXWdtfqpQU9tgXWfBFaDlLROFXEOVDzQEMkRoU7vDIi$>> > > 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 > > [getdoks.org]<https://urldefense.com/v3/__https:/getdoks.org__;!!HL9eAG-pe8ETeg!ZrMzG75stPrzIflnRbVqP3_kLlLaKRPPBXkFvHRbyOowNqu0ieXWdtfqpQU9tgXWfBFaDlLROFXEOVDzQEMkRrSY78xj$>>, > > 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 > > [docusaurus.io]<https://urldefense.com/v3/__https:/docusaurus.io/docs/versioning__;!!HL9eAG-pe8ETeg!ZrMzG75stPrzIflnRbVqP3_kLlLaKRPPBXkFvHRbyOowNqu0ieXWdtfqpQU9tgXWfBFaDlLROFXEOVDzQEMkRjNY1DsE$>> > > 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 > > [ci-hadoop.apache.org]<https://urldefense.com/v3/__https:/ci-hadoop.apache.org/view/Hadoop*20Ozone/job/ozone-doc-master/lastSuccessfulBuild/artifact/hadoop-hdds/docs/public/index.html__;JQ!!HL9eAG-pe8ETeg!ZrMzG75stPrzIflnRbVqP3_kLlLaKRPPBXkFvHRbyOowNqu0ieXWdtfqpQU9tgXWfBFaDlLROFXEOVDzQEMkRokgdhEN$> > > > > from ozone.apache.org > > [ozone.apache.org]<https://urldefense.com/v3/__http:/ozone.apache.org__;!!HL9eAG-pe8ETeg!ZrMzG75stPrzIflnRbVqP3_kLlLaKRPPBXkFvHRbyOowNqu0ieXWdtfqpQU9tgXWfBFaDlLROFXEOVDzQEMkRoxUjHBZ$> > > 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 > > [github.com]<https://urldefense.com/v3/__https:/github.com/apache/ozone-site/pull/28__;!!HL9eAG-pe8ETeg!ZrMzG75stPrzIflnRbVqP3_kLlLaKRPPBXkFvHRbyOowNqu0ieXWdtfqpQU9tgXWfBFaDlLROFXEOVDzQEMkRvcfG2yA$>>. > > > > 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<mailto:dev-unsubscr...@ozone.apache.org> > > For additional commands, e-mail: > > dev-h...@ozone.apache.org<mailto:dev-h...@ozone.apache.org> > ________________________________ Now for the fine fun print. You don’t need a ladder to see why homebuyers like Air Force Veteran Oden R. are Through the Roof about their Veterans United experience: “We’re home! Working with Veterans United was easy from beginning to end. We handled our part, and our loan squad took care of everything else. Buying our home turned out cooler than a polar bear's toenails!” For more cool words like Oden’s, check out our 325,000+ unedited, unfiltered homeowner reviews.<https://www.veteransunited.com/reviews/?utm_source=email&utm_medium=signature> And they’re not the only ones through the roof about Veterans United! We’re proud to be named 2022’s Top VA Lender by LendingTree, Bankrate, and Military.com. NOTICE: Email is not a secure medium. If you have important documents for your loan team, you can securely upload them to MyVeteransUnited<https://my.veteransunited.com/login?utm_source=referral&utm_medium=email_ftr&utm_campaign=email> or provide this information by fax, mail, or phone. Please don’t send sensitive personal information regarding your loan or personal identity in your emails or as an attachment. Mortgage Research Center, LLC is an Equal Opportunity Lender, not endorsed or affiliated with a government agency. NMLS # 1907 (nmlsconsumeraccess.org<http://nmlsconsumeraccess.org/>). Licensed in all 50 states. For State Licensing information, please visit www.veteransunited.com/licenses/<http://www.veteransunited.com/licenses/>
