Thanks Ethan for the initiative. +1 for the proposal. And +1 for Docusaurus. I've played with this doc framework a few months back. It is fine overall with decent community support as far as I can tell. Versioning is great, as well as i18n. Docusaurus v2 generates an SPA <https://en.wikipedia.org/wiki/Single-page_application> (super responsive) with React. When JavaScript is disabled it is still somewhat <https://github.com/facebook/docusaurus/issues/3030> usable.
We might even be able to integrate full-text search <https://docusaurus.io/docs/search> (e.g. Algolia) later on. -Siyao On Aug 29, 2023 at 1:34:48 PM, Ethan Rose <er...@cloudera.com.invalid> wrote: > 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 > > > > > > > > > >
