Awesome Research. As long as we can maintain documentation for all our versions, I agree we should overhaul the website. Improving our SEO and making it easier for people to contribute to the project are crucial concerns for us helping us grow the community. As for the static site generator we use: I think using the tool with the largest and most active community is probably best. It will mean that there is better support and likely more robust feature set and documentation to take advantage of.
On Thu, Feb 10, 2022 at 5:51 PM Nicholas Sorrell <n...@cint.io> wrote: > I did some research tonight and here are my findings. > > - Are there examples of other sites using Hugo? There are sites using > static site generators (SSG) and below is a quick survey of what's being > used. > + The following sites use docusaurus (MIT) > * Yunikorn: https://github.com/apache/incubator-yunikorn-site > * InLong: https://github.com/apache/incubator-inlong-website > * Shenyu: https://github.com/apache/incubator-shenyu-website > * Linkis: https://github.com/apache/incubator-linkis-website > * Seatunnel: https://github.com/apache/incubator-seatunnel-website > * Eventmesh: https://github.com/apache/incubator-eventmesh-site > * StreamPipes: > https://github.com/apache/incubator-streampipes-website > + The following sites use Jekyll (MIT) > * Nuttx: https://github.com/apache/incubator-nuttx-website > * brpc: https://github.com/apache/incubator-brpc-website > * Tuweni: https://github.com/apache/incubator-tuweni-website > * Wayang: https://github.com/apache/incubator-wayang-website > * Pegasus: https://github.com/apache/incubator-pegasus-website > * Livy: https://github.com/apache/incubator-livy-website > + The following sites use Vuepress (MIT) > * Doris: https://github.com/apache/incubator-doris-website > * Teaclave: https://github.com/apache/incubator-teaclave-website > + The following sites use Hugo (Apache) > * Kyuubi: https://github.com/apache/incubator-kyuubi-website > (doesn't do docs) > + The following sites use Eleventy (MIT) > * Annotator: https://github.com/apache/incubator-annotator-website > > - Can we maintain multiple versions of the docs using Hugo? > + I think so. If using Docsy, they address that here: > https://www.docsy.dev/docs/adding-content/versioning/ > * An example of a site doing this is here (top right corner is > version switcher): https://www.kubeflow.org/docs/ > + I also found Doks, which is an npm wrapper around Hugo. This page > describes versioning: > https://getdoks.org/docs/extensions/versioned-documentation/ > > > > ________________________________ > From: Jasper Blues <jas...@liberation-data.com> > Sent: Thursday, February 10, 2022 4:36 PM > To: dev@age.apache.org <dev@age.apache.org> > Subject: Re: [DISCUSS] Website Overhaul > > Sounds great. Also visible links in and out of the site should help with > Google site ranking as well as sharing. For example, by giving bloggers, > social media users etc links that relate directly to their talking points. > > > > On Feb 10, 2022, at 10:02 PM, Nicholas Sorrell <n...@cint.io> wrote: > > > > All, > > > > I wanted to propose that we overhaul the website ( > https://github.com/apache/incubator-age-website) to make it easier to > contribute to, easier to modify, more extensible, more accessible, and > easier to optimize for searching and performance. > > > > When I created the site, there were a couple of a factors in the design > decisions: > > > > Time - we were racing to get something done and presentable before a > conference the team was presenting at. This meant creating a site with > minimal "flare." > > Libraries - when we built the site way back then, we weren't sure what > 3rd party libraries we could incorporate. We weren't sure if Apache had > rules limiting the use of them, so we chose to use no libraries. This also > impacted the site (negatively in my opinion). > > > > Since then, we've seen other Apache sites using 3rd party libs and we > now have time to redesign the site. I propose that we redesign the site > using Hugo. This gives us the ability to utilize Markdown, which is much > more accessible for contributors, and also offers more extensibility > through themes and plugins. I think it could also make the process of > generating the docs easier but I haven't fully investigated that. > > > > Another negative about the current website is linking to content. > Because of the way that I've utilized anchors to show/hide content, this > keeps the URL slug the same no matter where you go, which makes it > difficult to share, for example, a "Getting Started" page with someone. > > > > So in summary, here are the potential benefits I see: > > + easier to modify: because the content is written in markdown, it is > easier for people change existing pages without knowledge of HTML/CSS/JS > > + easier to contribute: again, because we will use markdown for content, > it is easier for people to contribute new content > > + more extensible: because Hugo has a large ecosystem, we can tap into > the work of others > > + more accessible: this redesign will also have a focus on > accessibility so all users can engage with the content > > + better SEO: designing with SEO in mind so that users can find out > about AGE is important > > + possibly easier to build docs: right now we're using a Github workflow > to generate these, and we could possibly wrap all of this into a single > step of static site generation with Hugo > > + possible blog: another important aspect of both SEO and community > engagement is a blog, which can show examples and use cases of AGE's new > functionality with each release. The approval process for blog posts should > probably part of a separate conversation. > > > > Looking forward to hearing the community's thoughts. > > > > Thanks, > > Nick Sorrell > > > >
