You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@bigtop.apache.org by Olaf Flebbe <of...@oflebbe.de> on 2020/12/29 12:06:19 UTC
Bigtop Site: Input needed
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
Re: Bigtop Site: Input needed
Posted by Olaf Flebbe <of...@oflebbe.de>.
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 <ev...@apache.org>:
>
> 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 <toscano.luca@gmail.com <ma...@gmail.com>> 於 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 <sekikn@apache.org <ma...@apache.org>> 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 <sekikn@apache.org <ma...@apache.org>>
> >
> > On Wed, Dec 30, 2020 at 12:56 PM Evans Ye <evansye@apache.org <ma...@apache.org>> 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 <of@oflebbe.de <ma...@oflebbe.de>> 於 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
> > >>
> > >>
Re: Bigtop Site: Input needed
Posted by Olaf Flebbe <of...@oflebbe.de>.
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 <ev...@apache.org>:
>
> 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 <toscano.luca@gmail.com <ma...@gmail.com>> 於 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 <sekikn@apache.org <ma...@apache.org>> 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 <sekikn@apache.org <ma...@apache.org>>
> >
> > On Wed, Dec 30, 2020 at 12:56 PM Evans Ye <evansye@apache.org <ma...@apache.org>> 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 <of@oflebbe.de <ma...@oflebbe.de>> 於 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
> > >>
> > >>
Re: Bigtop Site: Input needed
Posted by Evans Ye <ev...@apache.org>.
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 <to...@gmail.com> 於 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 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 <se...@apache.org> 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 <se...@apache.org>
> >
> > On Wed, Dec 30, 2020 at 12:56 PM Evans Ye <ev...@apache.org> 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 <of...@oflebbe.de> 於 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
> > >>
> > >>
>
Re: Bigtop Site: Input needed
Posted by Evans Ye <ev...@apache.org>.
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 <to...@gmail.com> 於 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 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 <se...@apache.org> 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 <se...@apache.org>
> >
> > On Wed, Dec 30, 2020 at 12:56 PM Evans Ye <ev...@apache.org> 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 <of...@oflebbe.de> 於 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
> > >>
> > >>
>
Re: Bigtop Site: Input needed
Posted by Luca Toscano <to...@gmail.com>.
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 <se...@apache.org> 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 <se...@apache.org>
>
> On Wed, Dec 30, 2020 at 12:56 PM Evans Ye <ev...@apache.org> 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 <of...@oflebbe.de> 於 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
> >>
> >>
Re: Bigtop Site: Input needed
Posted by Luca Toscano <to...@gmail.com>.
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 <se...@apache.org> 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 <se...@apache.org>
>
> On Wed, Dec 30, 2020 at 12:56 PM Evans Ye <ev...@apache.org> 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 <of...@oflebbe.de> 於 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
> >>
> >>
Re: Bigtop Site: Input needed
Posted by Kengo Seki <se...@apache.org>.
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 <se...@apache.org>
On Wed, Dec 30, 2020 at 12:56 PM Evans Ye <ev...@apache.org> 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 <of...@oflebbe.de> 於 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
>>
>>
Re: Bigtop Site: Input needed
Posted by Kengo Seki <se...@apache.org>.
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 <se...@apache.org>
On Wed, Dec 30, 2020 at 12:56 PM Evans Ye <ev...@apache.org> 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 <of...@oflebbe.de> 於 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
>>
>>
Re: Bigtop Site: Input needed
Posted by Evans Ye <ev...@apache.org>.
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 <of...@oflebbe.de> 於 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
>
>
>
Re: Bigtop Site: Input needed
Posted by Evans Ye <ev...@apache.org>.
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 <of...@oflebbe.de> 於 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
>
>
>