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 <http://gohugo.io/> * Zola: https://www.getzola.org <https://www.getzola.org/> (* Ninja) I looked at various other Project’s design-wise: I liked arrow.apache.org <http://arrow.apache.org/> most, it’s clean. It looks like built with ninja and a custom layout Hadoop.apache.org <http://hadoop.apache.org/> is built with hugo with a custom layout (not adaptable for us), looking not-so-good. https://kubernetes.io <https://kubernetes.io/> and many lot more are built with hugo and https://www.docsy.dev/ <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 <http://bigtop-ananke.oflebbe.de/> Source: github.com/oflebbe/bigtop-site <http://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 <http://bigtop-docsy.oflebbe.de/> Source: github.com/oflebbe/bigtop-site-docsy <http://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
