Hi everybody, Thanks a lot Olaf for all the efforts! Going to add 2c from the community perspective of a fresh member related to what I was looking for when me and my team were deciding if/how to move to Bigtop. What I usually like in websites about projects is that there is a quick and easy way to get the following information during the first minute of navigation (or even less): - A clear and concise description about what the project is doing and releasing. - Quick links about docs containing snippets of code describing few simple use cases and how they are handled, or even better quick snippets to copy/paste commands to execute to try most common use cases. - Possibly a date or reference that tells me how often the project is releasing, or how to find the info (via github / Jira / etc..).
The http://bigtop.apache.org front page looks good for the first point, but it would be great to have a couple of sections like "Here's how you build one package with Docker" or "Here's how you create a cluster from scratch to test the latest packages via Docker". It is very powerful as message since it captures the attention of the user looking for some information, and it could be a first jump to Confluence. I am saying that since I found Confluence via Google search (I know that there is a "Wiki" link in the dropdown menu' but I didn't really think to check there at the time) and I personally found it a little confusing (not the Bigtop specific one, in general) and I felt that the project was not updated a lot since most of the links were pointing to 1.1/1.2 releases. At this point it wasn't still clear to me what Bigtop was really about, for example the fact that I could have rebuilt packages selectively applying patches on top etc.. simply using a Docker image. This is an amazing and powerful workflow that you all built, and it should be crystal clear to all (new) users how simple and effective are the tools available! I know that the info was there, but for some reason my brain was not processing it :D (this is why I suggested the quick code-snippets in the front page). After a bit of research I found Jira, and then I figured out the process of releasing etc.. For a new user, official website + Confluence + Jira + github are surely overwhelming if there is not a clear link between them (at least from my point of view). Among the examples that Olaf brought up, I think that http://arrow.apache.org/ is really neat (especially the docs page, very clean) and I also like https://kubernetes.io/ and its documentation (that IIUC is docsy-based right?). The http://bigtop-docsy.oflebbe.de/ is very nice, I like the fact that the vertical color bars are highlighting different concepts/things, and it also feels more easy to follow. I completely understand what Evans says about the efforts to maintain a new versioned documentation though, so ananke is a viable option as well. Hope that helps! Luca On Wed, Dec 30, 2020 at 7:55 AM Kengo Seki <[email protected]> wrote: > > 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 > >> > >>
