Hi everybody, Was not able to work on the homepage for almost a month.
Special thanks to Kengo, for the recommendation regarding the links! I should have read the docs more carefully. The overall consensus seems to be to continue the docsy path. I am planning to making slow progress: Recreating the Bigtop Website (i.e. supporting the same links we have right now). When I am more confident that I can build a working site, I would ask INFRA to setup a bigtop-site git repo and a testing space. Meanwhile I will serve the test site at http://oflebbe.de/bigtop-site-docsy repo is github.com/oflebbe/bigtop-site-docsy Best Olaf > Am 31.12.2020 um 11:19 schrieb Evans Ye <[email protected]>: > > I like the user input from Luca, thanks for sharing that. > Overall I think it's the "lack of doc" problem that we're having for a long > time. But pointing out what is important to the users is a valuable info for > us so that we can start from there first and extend further. > > I just want to add one more thing: as long as the contribution is good to the > community and align with the community direction, I'm up for it. So feel free > to explore and contribute if "Docsy" is more preferred. > > > > Luca Toscano <[email protected] <mailto:[email protected]>> 於 > 2020年12月30日 週三 下午6:02寫道： > 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 <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/ <http://arrow.apache.org/> is really neat > (especially the docs page, > very clean) and I also like https://kubernetes.io/ <https://kubernetes.io/> > and its > documentation (that IIUC is docsy-based right?). The > http://bigtop-docsy.oflebbe.de/ <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] > <mailto:[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 > > <https://themes.gohugo.io/docsy/#documentation> > > > > Kengo Seki <[email protected] <mailto:[email protected]>> > > > > On Wed, Dec 30, 2020 at 12:56 PM Evans Ye <[email protected] > > <mailto:[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] <mailto:[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 <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 > > >> > > >>
