My two cents: First of all, thank you for putting in the effort on the bigtop site. The example looks super great!
I'd vote for Ananke for the following reasons: 1. Seems like this solution strikes the balance between the maintenance effort and the result we want. 2. The docs are all on confluent now so it's as good as it is if we decide to stay on confluent. 3. Even though we just have the site updated, I think it's a huge plus for our branding/imaging. And somewhat telling users that we're keep evolving and up-to-date. 4. "Docsy" or "Exploring different options" are too much effort for now and future that we can't carry down the road. - Evans Olaf Flebbe <[email protected]> 於 2020年12月29日 週二 下午8:06寫道： > Hi, > > As previously discussed I had a look on making the website authoring more > accessible. > > I totally underestimated it, my head hurts now (see below) :) > > And I am now at crossroads, need your input: > > First I decided to look at static site generaters, these are candidates: > * Hugo : gohugo.io > * Zola: https://www.getzola.org > (* Ninja) > > I looked at various other Project’s design-wise: > > I liked arrow.apache.org most, it’s clean. It looks like built with ninja > and a custom layout > Hadoop.apache.org is built with hugo with a custom layout (not adaptable > for us), looking not-so-good. > https://kubernetes.io and many lot more are built with hugo and > https://www.docsy.dev/ theme looking very professional. > > I didn’t want to use ninja for some reason and decided to look into hugo: > > * A plus for hugo was support for asciidoctor files out of the box, as Cos > was suggested. > > * big community repository of ready-made themese. But none if them was a > 100% fit, so I did example bigtop landing pages: > > Examples > ======== > > Hugo / Ananke theme: > ================= > > Example: http://bigtop-ananke.oflebbe.de > Source: github.com/oflebbe/bigtop-site > (Install asciidoctor as an additional prerequisite) > > In order to understand Hugo I followed the quickstart and the recommended > ananke theme: > Cons: > * I had to bang my head for two days against the wall to implement a > pulldown navigation menu. (The ASF Menu) > * Had to fight sizes and image scaling > * No support for docs, if we would move docs from confluence with > versioning support to the site. > (i.e. seperate bigtop-1.4 from bigtop-1.3 as an example), > * Allmost no docs. > > Pro: > * Looks ok-ish > * Clean and easy to understand. > * Design is Blog-centric > > Hugo / docsy theme: > =================== > Example: http://bigtop-docsy.oflebbe.de > Source: github.com/oflebbe/bigtop-site-docsy > > There are a lot of Linux Foundation/Cloud projects built on this theme, > but that’s a pity as well: All the 3rdparty services used and advertised > (twitter, stackoverflow, github, google analytics, google search ) are > hardcoded in the design. Either override almost all these layout templates > or actually play on these channels as well ? > > Cons: > * Harder to use > * Banging my head against the wall to get PostCSS running correctly. > * Banging my head for a day to get the "The ASF“ dropdown menu working > (still doesn’t look right) > * Fight the social network links and so on in the templates > * Sometimes it seems to trigger bugs in hugo > > Pro: > * Documentation templating seems to work, support for versioned docs > * Mature Design system > > > General Observations > ================== > > It seems like dropdown navigation menus are not a good idea: > * From accessibilty perspective it is complex to support for vision > impaired persons > * On mobile on docsy theme they aren’t rendered at all (no idea why) > * Changing that we need to provide more content (hadn’t thought about that > previously) > > We need to decide what additional social media channels we would like to > use (twitter etc ..) > > Need a perspective of how we do documentation: Stay on confluence or move > to Markdown, into the site. > > We offer different Downloads in „Downloads“ and „Releases“. It feels > weird. And the Instructions how to use are buried deep in confluence and in > the Readme.md (Readme is not linked from landing page) > > =====> Your input needed: <======= > > What do you think about what will fit a future landing page best, what > will your work/our audience supporting most? > > * Everything to complex: > We should stay on current tooling and focus on content , because of > limited resources. > * Docsy: > Start with a landing page and move over stuff later > * Ananke: > Only offer a landing page and head over to confluence with everything > else > * Exploring different options > (suggestions, if possible) > > Sadly; I am note able to finish this, I had and still a few days off now > the clock is ticking. > > What I learned from it (besides tons of CSS/HTML fine points): We should > improve current content first, work on tooling second. > > What conclusion would you draw ? > > Best, > Olaf > > >
