Hi Geode Dev Community,
My name is Patrick Harmon, and I'm a member of the SAS team working to
modernize Geode. I was real interested in the recent effort to update the
Apache Geode project website:
https://issues.apache.org/jira/browse/GEODE-10468 (Modernization of Apache
Geode Website)
For the past few months, my colleague Bryan Behrenshausen and I have been
working on issues related to this effort. Some of these include:
https://issues.apache.org/jira/browse/GEODE-10485 (Upgrade to latest website
template)https://issues.apache.org/jira/browse/GEODE-10582 (documentation
modernization)https://issues.apache.org/jira/browse/GEODE-9956 (update website
generation tools)
Our work has been progressing, and I'd like to share with you what we've done
so far. I'd also like to get your feedback on our proposed updates and some of
the process changes we're imagining.
The first thing we did was port the Geode website to the docusaurus-based ASF
website template:
https://github.com/apache/apache-website-template
Starting from that template, we have been able to continue modernizing the
Geode site. And by working with the template, we were able to ensure that the
new site is aligned with ASF branding and trademark policies:
https://issues.apache.org/jira/browse/GEODE-10474 (Branding updates on website)
I plan to raise a draft PR when it's a little more polished, but the code
currently resides on a feature branch:
https://github.com/harmoncoffee/geode-site/tree/GEODE-10468
You can see a working prototype of the new site here:
https://apachegeode.pharmondev.com/
(It's hosted on AWS, and it pulls my local branch and refreshes when commits
are done. I wanted to wait until there was enough progress on it to share here.)
Here's a list of the primary tasks we've completed so far:
- Using a docusaurus based environment for hosting the geode-site. -
Organization of existing docs to mostly match the old website, on the side
navigation bar. - Arranging the initial site page to provide most of the same
content from geode.apache.org
And here's what's in progress:
- Migration of Apache Geode 1.15 docs- Validating all links, images, and
anchors are fixed when rearranging the file directories. I believe at
approximately 600 links are still broken, and 200 anchors need fixing (at least
based on automatic docusaurus validation)
On our list (but not yet started) are:
- Once Completed with 1.15, add the new 2.x versions to the doc- Migration of
native docs, for C++ and .NET 1.15 versions, and if need any changes for 2.x
add that- Documentation on how to contribute to geode site when using
docusaurus- Removal of old geode docs on the main 1.15, and 2.x branches
A few final notes, too:
1. This proposed site upgrade does change the working location of the Geode
documentation. Currently, the documentation resides in the Geode project
repository and gets built with a Ruby-based toolchain:
https://github.com/apache/geode/tree/develop/geode-docshttps://github.com/apache/geode/tree/develop/geode-book
Docusaurus-based sites expect the documentation to be in the same location as
the website files themselves—hence the need to migrate all existing
documentation to the geode-site repository
(https://github.com/apache/geode-site). I do not believe there would be any
reason to retain documentation inside the Geode development rather just in the
geode-site repository. So with this change, we would likely be suggesting the
deprecation of the previous documentation system and location.
2. Docusaurus can utilize markdown, very similar to the existing documentation.
So I have stripped most of the files and put them into markdown files, then
adjusted the yaml front matter to organize and name the content. Since I'm
utilizing auto-formatting of docusaurus, I went through each document and
explicitly ordered them with the front matter. As you review, please help me
ensure that our content listings are correct.
I was talking with Jinwoo Hwang (Geode PMC member and my SAS colleague), and my
initial thought is to keep just 1.15.x, and 2.x documentation versions updated
on the website, as these are the only two supported Geode versions. This can be
revisited if we need to, but I believe that once I have the entirety of the
documentation renamed and formatted, with links working, I will go through a
diff phase of the other versions and see how much really changed, maybe add
those independently if we believe it's required. I have not analyzed this
separately yet.
I would love to hear some feedback, thoughts, and suggestions.
Thank you, Patrick Harmon @patrickharmon (Geode Jira) @harmoncoffee (GitHub)
