IRC meeting: website overhaul

[Richard Downer <ri...@apache.org>]

All,

There was a meeting on IRC earlier today to discuss ideas for overhauling
the website. I wasn't able to join for the whole meeting but I did leave my
IRC client running to capture the meeting. In line with the principle that
all discussions which lead to decisions must sooner or later be discussed
on the mailing list, and for the benefit of those unable to join, below is
a transcript of the meeting.

[We should really be using ASFBot to make minutes of meetings on the IRC
channel but it appears that I do not have permission to do so. I will now
try to find out how to resolve that, and next time ASFBot should be able to
prepare meeting minutes in a more presentable way.]



[16:01:53] *<alx>* hi @channel - website discussion?

[16:02:22] *m4rkmckenna* (~m4rkmcken@212.250.191.72) joined the channel.

[16:02:35] *Thomas* (57f64e2e@gateway/web/freenode/ip.87.246.78.46) joined
the channel.

[16:02:40] *<geomacy>* that time already!?

[16:02:58] *<Thomas>* Looks like it, already 4pm

[16:02:58] Thomas is now known as *Guest11370*

[16:03:04] *<alx>* indeed - the week is almost over

[16:03:45] *<alx>* so the things i'm thinking we cover

[16:03:48] *<alx>* - Thomas's work

[16:04:01] *<alx>* - search

[16:05:09] *tbouron* (~thomasbou@87.246.78.46) joined the channel.

[16:05:10] *<alx>* - getting started improvements

[16:05:13] *<alx>* - what other snazzy things we can do (ascii
cinema?  graphics?)

[16:05:20] *<alx>* anything else?

[16:05:40] *<geomacy>* sounds comprehensive...

[16:05:52] *<tbouron>* sounds good to me

[16:06:30] *<alx>* cool

[16:06:45] *<alx>* so item 1, thomas's work=

[16:06:59] *<alx>* https://tbouron.github.io/brooklyn-docs/

[16:07:24] *<richarda_>* *ASFBot*: meeting start

[16:07:25] *<ASFBot>* You don't have enough karma for this request

[16:07:33] *richarda_* (~richardas@ipv4nat.frontiertown.uk) left IRC.
(Quit: Textual IRC Client: www.textualapp.com)

[16:07:44] *richardasf* (~richardas@ipv4nat.frontiertown.uk) joined the
channel.

[16:07:45] Topic is *Apache Brooklyn project *https://brooklyn.apache.org*.
LOGGED to *https://gitter.im/brooklyncentral/brooklyn

[16:07:45] Set by *richarda_* on 4 February 2016 at 15:20:24 GMT

[16:07:45] Mode is *+cnt*

[16:07:49] *<richardasf>* *ASFBot*: meeting start

[16:07:50] *<ASFBot>* You don't have enough karma for this request

[16:07:51] *<alx>* i really like the cleanup

[16:08:06] *andreaturli* (~andreatur@93-61-99-89.ip146.fastwebnet.it)
joined the channel.

[16:08:19] *Justin__* (b213d2a2@gateway/web/freenode/ip.178.19.210.162)
joined the channel.

[16:08:36] *<andreaturli>* hello

[16:08:39] *<geomacy>* +1

[16:08:46] *<andreaturli>* is the website discussion happening here?

[16:08:49] *<alx>* tend to agree on home page as you scroll it would be
nice to see Apache Brooklyn in the header

[16:08:52] *<alx>* *andreaturli* yes

[16:08:57] *<andreaturli>* oh ok, thanks

[16:09:24] *<alx>* not sure if the feather could shrink and logo appears,
so that it looks like the other pages once you've scrolled down a bit

[16:09:25] *<tbouron>* that’s not an issue, I can remove the feather and
always display the apache brooklyn logo

[16:09:49] *<andreaturli>* +1 *tbouron* as I've already said on the mailing
list

[16:09:51] *<alx>* it's nice _not_ having apache brooklyn in both the
header and the jumbotron when you land

[16:10:08] *<tbouron>* Agree, that’s what I replied to Andrea

[16:10:11] *<alx>* not sure how easy it is to do that morph tho *tbouron*

[16:10:38] *<geomacy>* is it not possible to just leave it looking exactly
the same as the other pages, i.e. with feather and Apache Brooklyn

[16:10:50] *<geomacy>* but feather is just a bit smaller?\

[16:10:53] *<tbouron>* we need to put something there to “fill” the room. I
was thinking SVG animation

[16:10:56] *<alx>* but then it says apache brooklyn twice due to the
jumbotron *geomacy*

[16:10:57] *Justin__* (b213d2a2@gateway/web/freenode/ip.178.19.210.162)
left the channel.

[16:11:35] *drigodwin* (~drigodwin@129.53.125.91.dyn.plus.net) joined the
channel.

[16:11:38] *<geomacy>* hm suppose that looks poor, fair enough

[16:11:41] *<richardasf>* FTR, according to
https://www.apache.org/foundation/marks/pmcs "Projects may may choose to
use the Apache feather in their logo if they wish" - so it's not compulsory
that we give the feather a prominent place on the homepage.

[16:11:58] *<andreaturli>* something easy like http://cassandra.apache.org/
?

[16:12:01] *<tbouron>* good to know richard, thanks

[16:12:22] *<richardasf>* Actually the Apache visual identity changed
recently and there's a new feather -
https://www.apache.org/foundation/press/kit/#links

[16:12:22] *<geomacy>* one small point related to the three items at the
bottom of the page

[16:12:34] *justinThompson* (~justinTho@178.19.210.162) joined the channel.

[16:12:40] *<alx>* personally i love how the landing page works and how the
subsequent pages look in thomas's rework, with the feather and all

[16:13:10] *<alx>* richardasf i think *tbouron* is using the new feather
already

[16:13:36] *<alx>* my comment is just a minor one, it would be nice on
landing page if you scroll down if the top could morph to mention brooklyn

[16:13:54] *<alx>* if that's hard then we just go with what *tbouron* has
done

[16:13:59] *<alx>* methinks

[16:14:00] *<andreaturli>* good suggestion *alx* that will be ideal I think

[16:14:01] *<geomacy>* minor point, could we ensure the three items at the
bottom of the page each contain useful links to the reference pages where
each aspect is explained in detail

[16:14:07] *<andreaturli>* especially on small screens

[16:14:27] *<geomacy>* there are various websites like this (not mentioning
any by name!) that contain the marketing veiw

[16:14:29] *<geomacy>* view

[16:14:47] *<geomacy>* but fail to provide links to the 'meat' that lets
you figure out what it really means

[16:14:55] *<geomacy>* from a developer point of view; which is very
frustrating

[16:15:41] *<alx>* as for the bottom section i think "get in touch" through
those 3 mechanisms isn't the best closing call to action for someone who
has scrolled to the bottom

[16:16:01] *<tbouron>* I’m not following your point *geomacy*, what are you
talking about exactly?

[16:16:28] *<geomacy>* the three columns/panels labelled "Use Apache
brooklyn for …"

[16:16:35] *<andreaturli>* speaking of which, we should probably rethink
about the Documentation section: the navigation is quite hard and the lack
of a search bar make it even more difficult

[16:16:56] *<geomacy>* agreed

[16:17:08] *<alx>* *geomacy* are you talking the bottom section or the "use
brooklyn for..." section ?

[16:17:08] *<tbouron>* I also plan to do that in a following PR Andrea

[16:17:14] *<geomacy>* the "Use Apache brooklyn for …"

[16:17:21] *<andreaturli>* wow *tbouron*, you read my mind!

[16:17:57] *<andreaturli>* are you looking at things like readthedocs or
maybe we don't want to introduce another technology?

[16:18:09] *<tbouron>* I actually already searched last night for the
search feature, there is https://cse.google.co.uk/cse/all whcih can be
completely customised to match our branding

[16:18:25] *<alx>* right *geomacy*, those sections should be links, or at
least have links

[16:18:31] *<geomacy>* so under Modellng there is a link to components, but
it would be good to add a link  to the first word to pages explaining
blueprints etc.

[16:18:37] *<geomacy>* but no links in the other sections

[16:18:55] *<geomacy>* e.g. the list of policies could link to the
reference pages for each

[16:18:57] *<alx>* that seems a v good idea

[16:19:34] *<geomacy>* "Monitor" could be linked to
https://tbouron.github.io/brooklyn-docs/v/latest/start/managing.html

[16:19:35] *<geomacy>* and so on

[16:19:35] *<tbouron>* that’s not an issue, I can add links if you wish
*geomacy*. I just tool what was already there. Didn’t reword that

[16:20:19] *<geomacy>* +1 to suggestion from @*andreaturli*

[16:20:59] *<alx>* what about the bottom section of landing page ?

[16:21:12] *<tbouron>* But remember that the point is to be super simple. A
new user need to be able to grasp what brooklyn is for in 5 -10 secs
otherwise one will it brush away. That’s why most of the landing page are
now super simple with a very clear tagline, which I tried to achieve with
the “Your application, any clouds…. "

[16:21:25] *<alx>* +1 *tbouron*

[16:21:51] *<andreaturli>* I like your thinking, *tbouron*

[16:22:29] *<geomacy>* *alx* do you mean that a "get in touch" section is
not "compelling" enough as the last panel?

[16:22:45] *<geomacy>* i.e. either drop it or replace it with something
more impressive?

[16:23:03] *<alx>* *geomacy* feels like it should be one of the three
columns, not all three columns

[16:23:10] *<tbouron>* re readthedocs, I’m not sure I like this solution as
you are tied to an external service. I think we can improve a lot our docs
ourselves

[16:23:52] *<alx>* also i notice we've lost the twitter / irc / github
icons from the header

[16:24:00] *<alx>* -1 readthedocs

[16:24:28] *<andreaturli>* no-new-tech-please *alx* ?

[16:25:17] *<alx>* we do a lot of smarts to deal with multiple versions and
formatting and clipboards etc that readthedocs will very likely lose

[16:25:33] *<tbouron>* re social icons: we didn’t loose them, there are now
at the bottom :) Currently, there is no room for more things in the menu. I
wanted to reduce the number of menu items but it was not in the scope of my
PR

[16:25:45] *<andreaturli>* I've seen that in many sites, for example
http://hyperledger-fabric.readthedocs.io/en/latest/index.html and it looked
good to me. *tbouron* it is based on sphinx and I think you can install it
on-premise

[16:25:47] *<alx>* i'm a big believer in the devil we know

[16:26:17] *<alx>* *tbouron* social icons aren't present at all once you've
left the first page

[16:26:44] *<alx>* not saying that's a bad thing necessarily however

[16:27:28] *<tbouron>* I don’t think that’s important TBH. I the community
feels like it should be there, then I think the more appropriate place for
them is the footer, not the header

[16:27:47] *<alx>* no strong feelings for that

[16:28:28] *<alx>* i think a "Learn More" column would be useful on the
front page

[16:28:36] *<tbouron>* Would be interesting to have the stats but in my
experience, the click rate on these icons are super small

[16:29:02] *<alx>* what if the bottom section were reworked to have three
columns as follows

[16:29:42] *<alx>* - Learn More - You can [see what a blueprint looks like]
or view the [feature list].

[16:30:13] *<tbouron>* So since we are talking about the main menu, my plan
to to group “learn more” and “getting started” together, grouping
“community” and “developpers” and keep documentation so we end up with only
4 items

[16:30:38] *<alx>* - Join the Community - Ask us questions on [IRC] or
[Stack Overflow], or [view the mailing list] or [write to the mailing list].

[16:30:53] *<alx>* - (and one more?)

[16:31:13] *<alx>* *tbouron* good topic - i think community and developers
could be combined


[16:31:29] *<alx>* not sure about "learn more" vs " get started" -- think
those are to two very different audiences

[16:31:51] *<alx>* learn more is for people who want to read about, whereas
get started is users

[16:32:50] *<tbouron>* Disagree. Thoses sections are for beginners in
brooklyn and I see the “Learn more” as a deeper first explanation of
Brooklyn concepts

[16:32:54] *<andreaturli>* *alx*: I don't think this separation is
immediately clear

[16:33:15] *<alx>* (returning to panels in the bottom section, third one) -
Get Started - Write and launch your first blueprint, and see the deployment
and management capabilities of Brooklyn.

[16:34:17] *<tbouron>* You already have a link to this section on the “Get
started” section Alex

[16:35:13] *<alx>* *tbouron* website should be optimized towards people who
are new to brooklyn, shouldn't it?  which means we shouldn't make that a
single user category.  i think there's a big split between people who just
want to get their hands dirty vs people who want to read about it.

[16:35:17] *<andreaturli>* I think we should find a place in the landing
page for this
https://tbouron.github.io/brooklyn-docs/learnmore/blueprint-tour.html

[16:36:54] *<tbouron>* I sort of agree but I usually go to the
documentation when I want to get my hands dirty, not “learn more”. Do you
have any example websites which do that?

[16:36:58] *<alx>* that's another idea -- we could just make the landing
page really long, containing that embedded, and containing also some nifty
graphics for deploy and manage (maybe asciicinema showing `br deploy` then
`br apps` ?)

[16:37:10] *<andreaturli>* similar to https://www.terraform.io/ ?

[16:38:01] *<andreaturli>* I don't want to give the impression that
modeling-deploying-managing is something sequential tho

[16:38:12] *<andreaturli>* like it seems reading terraform.io

[16:38:38] *<alx>* *tbouron* HL has "key concepts", TF has "intro".  i
think it's quite common that sites have a gentle intro separate to the
thorough documentation.  that's what Learn More is.

[16:38:49] *<andreaturli>* that's why I think the blueprint-tour or
something similar is good to highlight the 3 main features at once

[16:39:06] *<alx>* *andreaturli* except blueprint tour doesn't capture
in-life aspect

[16:39:17] *<alx>* or maybe it does ... i guess it's sort of implicit ?

[16:40:09] *<andreaturli>* I think so, we should capture that somehow as
well, but I think you got my idea

[16:40:38] *<justinThompson>* it feels to me like there is a bit of a step
missing between “Use Apache brooklyn for …” and “getting started“

[16:40:41] *<andreaturli>* it's probably more a circular graph where node
are modelling, deploying and managing

[16:40:57] *<andreaturli>* nodes*

[16:41:36] *<alx>* the circle is a bit hackneyed isn't it?  plus, it's not
obvious you go from manage -> model.

[16:42:06] *<alx>* to me it is roughly sequential, to begin with, but then
it can go in any order

[16:42:28] *<justinThompson>* are we missing some kind of hook? like a nice
easy demo video

[16:42:31] *<alx>* it does feel like we need something snazzier

[16:42:36] *<alx>* +1 *justinThompson*

[16:42:55] *<alx>* either explanatory graphics for the "model / deploy /
manage" as thomas has laid them out

[16:43:09] *<alx>* or insert the blueprint tour as a new section

[16:43:20] *<alx>* and/or have an ascii cinema showing what you can do in
terms of deploying

[16:43:41] *<tbouron>* … and we go back to a complicated landing page which
we tried to avoid in the first place

[16:44:52] *<justinThompson>* well are we over simplifying if we cant get
all the information across?

[16:45:01] *<alx>* *tbouron* i think the complexity stems from the fact
that to understand what brooklyn does required a lot of reading and even
then it wasn't clear

[16:45:15] *<alx>* your work makes the page more attractive but it doesn't
address that

[16:45:45] *<alx>* it makes getting started easier which is a big help

[16:45:53] *<alx>* but we need to get the message across better

[16:46:08] *<justinThompson>* +1 *alx*

[16:46:30] *<justinThompson>* i think thats the crux

[16:46:54] *<alx>* the blueprint tour is effective, but i agree it's very
complex

[16:47:13] *<justinThompson>* and on the homepage you dont even know why
you want a blueprint tour

[16:47:55] *<tbouron>* agree to clarify the message but disagree to do it
by adding complex elements such as the blueprint tour. I tihnk this should
stay where it current is

[16:48:32] *<alx>* fair enough

[16:48:41] *<alx>* how do we get the clear message out then?

[16:48:42] *<andreaturli>* looking around for inspiration:
https://kubernetes.io/ is not great as well in get the message across, I
think

[16:49:22] *<andreaturli>* but the interactive tutorial idea looks good

[16:49:45] *<alx>* if you have sufficient cache IE you are google then you
can get pretty far without making your message clear :)

[16:50:26] *<tbouron>* Maybe the 3 column layout is not right. Maybe we
need something with a bit more text but with a layout a la kubernetes, i.e
alternate image/text

[16:51:09] *<justinThompson>* and with kubrenetes people are in a slightly
different mind frame, they are prepared to dig through and spend a bit more
time because its kubrenetes

[16:51:12] *<tbouron>* andreatruli you will note that their interactive
tutorial is not on the landing page ;)

[16:51:20] *<alx>* kub site could be a good one to follow

[16:51:49] *<alx>* feels like we need more but simpler elements on the
landing page

[16:51:56] *<andreaturli>* true *tbouron*, I was trying to re-use what we
have to help the message

[16:52:18] *<alx>* not saying we've solved the issue but as a direction to
work in i think that's a good one

[16:52:32] *<alx>* folks want to continue some brainstorming on that front
offline ?

[16:53:11] *<alx>* couple other topics...

[16:53:15] *<alx>* - search

[16:54:02] *<tbouron>* I actually already searched last night for the
search feature, there is https://cse.google.co.uk/cse/all whcih can be
completely customised to match our branding

[16:54:22] *<alx>* we need to fix this -- IE searching in the
documentations.  i don't think much time has been spent making this work
well.  *tbouron* can you see whether we can make more elegant use of google
search, prefer latest version, present results more nicely and easier to
use, etc ?

[16:54:34] *<alx>* not picking on you but it sounded like you had started

[16:54:38] *<alx>* snap

[16:54:41] *<alx>* great :)

[16:54:54] *<tbouron>* Yeah, integrate this will be simple enough

[16:55:03] *<alx>* next topic ... getting started improvements

[16:55:36] *<alx>* i think we should use a pure-bash example for getting
started, instead of the magic hidden TomcatServer

[16:55:52] *<geomacy>* +1

[16:56:17] *<tbouron>* +1. should also use pure YAML blueprint (that’s
probably what you are referring too *alx*)

[16:56:46] *<andreaturli>* +1

[16:57:01] *<alx>* maybe using templates 1-4 in
brooklyn-cli/src/main/resources/catalog.bom ?

[16:57:13] *<alx>* or maybe writing something new along similar lines ?

[16:58:09] *<alx>* someone want to think on that and propose something on
the list ?

[16:58:27] *<andreaturli>* back to the landing page I think as *geomacy*
said we should make modeling-deploying-managing simply links with some more
graphics and replace entirely the text there, as personally I think it's
too much for a landing page and not enough to explain properly.

[16:59:01] *<andreaturli>* for example we should introduce `blueprint`
before we use it later in the landing page "Congratulation! Next, let's
deploy a blueprint."

[17:00:06] *<justinThompson>* +1

[17:00:30] *<tbouron>* Wouldn’t it be a bit odd to have only titles without
helper text below? Also blueprint is currently introduced in the “Modeling”
block

[17:00:35] *<alx>* kubernetes.io was nice in that it was rather a good mix
of what and why on the landing page

[17:00:55] *<alx>* i think the text is just too dense (tp

[17:01:01] *<alx>* (typical, as i wrote it)

[17:01:22] *<justinThompson>* and can we just call it an application
instead of a blueprint at this point?

[17:01:42] *<justinThompson>* even just for the link

[17:01:51] *<alx>* blueprint is a good word -- i think we want to OWN the
idea of blueprints

[17:02:09] *<alx>* but maybe a la k8s page we make it a headline in a
section describing what we're about

[17:02:35] *<justinThompson>* its just at this point do people connect
blueprints with applications?

[17:03:01] *<tbouron>* “Blueprints describe your application” => Sounds
reather clear to me

[17:03:02] *<alx>* we do have to get across that you're blueprinting an
application, or maybe just infrastructure

[17:03:03] *<justinThompson>* maybe like you say we need to make that
cleared rather than changing it to applications

[17:03:28] *<alx>* if it isn't clear what we're blueprinting we've failed :)

[17:03:46] *<alx>* i gotta go soon -- so homework, thomas on search, and
all of us on different mockups for the landing page, trying to make clearer
what we do

[17:04:17] *<andreaturli>* do we have a good wireframe online tool to use?

[17:04:28] *<andreaturli>* not really good with those things but I'd like
to help

[17:04:29] *<alx>* good chat - a bit of a random walk but i think it is
needed because it isn't an easy thing to solve

[17:04:38] *<geomacy>* Folks are we concentrating too much on the front
page?

[17:04:39] *<alx>* TY all

[17:04:48] *<geomacy>* The front page is important but I think the deeper
issue about the docs is the overall structure and coverage

[17:04:48] *<geomacy>* of the docs in total, just fixing up the front page
is only the start of what we need to do.

[17:05:01] *<geomacy>* Worth pursuing on the mailing list?

[17:05:35] *<alx>* *geomacy* yes, continue on ML -- I think the front page
and the first example are the two most important things to improve

[17:06:06] *<alx>* if they do the job, we're good, and if they don't, we're
in trouble :) ... so no, i don't think we're concentrating too much there!

[17:06:48] *<alx>* there's a lot more we could do but people aren't going
to leave/stay because community and developers are two different menu items
vs one

[17:07:02] *<alx>* responding to biggest complaint i hear which is "i don't
get wtf you do" !

[17:07:25] *<andreaturli>* could we expand modeling into `modeling your
application` and so on and remove `Use Apache Brooklyn for ...` ?

[17:07:42] *<tbouron>* *geomacy* +1 but I deliberately reduced the scope of
my work, otherwise, the changes were going to be too big

[17:07:54] *DuncanG* (~duncangra@87.246.78.46) left IRC. (Ping timeout: 258
seconds)

[17:08:07] *<tbouron>* I plan to address the overall structure after this
work

[17:09:18] *<geomacy>* of course

[17:09:25] *<geomacy>* step by step1

[17:10:23] *<ASFBot>* GitHub: ahgittin opened a pull request:     Cleanup
search paths - https://github.com/apache/brooklyn-server/pull/646

[17:10:58] *<alx>* bfn + thx all

[17:11:06] *<tbouron>* I have to go folks, ttyl