Thank you for the investigation, Olaf! Both examples are really cool. I personally prefer the second option (docsy) because of its versioned documentation support, but also think Evans' opinion is reasonable so either is OK to me.
> 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? Just curiosity, isn't commenting out params.links.* in config.toml enough to hide the social network links? I tried the docsy example following the steps described in [1], and the links which are commented out in config.toml (e.g., Stackoverflow and Slack) seemed to be disabled in the footer. [1]: https://themes.gohugo.io/docsy/#documentation Kengo Seki <[email protected]> On Wed, Dec 30, 2020 at 12:56 PM Evans Ye <[email protected]> wrote: > > 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 >> >>
