Introductory landing page, versioning #22
Conversation
✅ Deploy Preview for cdevents ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
content/en/_index.html
Outdated
| <a href="https://cd.foundation/"><img src="https://raw.githubusercontent.com/cdfoundation/artwork/main/cdf/stacked/color/cdf-stacked-color.svg" width="20%"/></a> | ||
| {{< /blocks/lead >}} | ||
|
|
||
| {{< blocks/lead title="Benefits" color="white">}} |
There was a problem hiding this comment.
This block sounds nice, but I think it's too much text for the home page, especially with the current formatting in a thick font back on white, centred on the page.
Some ideas could be to have tiles with some short text or logos which could be expanded to the full text, or links to separate pages with the full content.
There was a problem hiding this comment.
At this stage of maturity of the product, the landing page should be considered to be a sales pitch. It should be a 2-3 minute read of the scale of a news article, making a handful of clear points to attract attention. The point of doing this on the landing page is exactly because it is self-filtering. Interested parties will scroll down and those reacting with no spark to the idea will navigate away.
You need a narrative because the concept is too abstract for people to grasp easily without explanation.
The formatting is an example of the trade-off that has to be made when trying to optimise a site for desktop and mobile use. The text appears somewhat on the heavy side on a large display, but on a tablet or mobile device it is pitched at the density and word spacing of newsprint.
We should keep in mind that this is a sales pitch for a virtual product currently, so words are necessary.
There was a problem hiding this comment.
I do agree that a narrative could be very valuable here. But these paragraphs are maybe a bit unnecessarily long for people to not stop reading before they reach the last paragraph. I don't know how to abbreviate the text really, but an alternative could maybe be to change most of the text to be non-bold, and emphasizing the most important sub-sentences in bold instead? Kind of how Tekton does it on https://tekton.dev/
There was a problem hiding this comment.
A couple of important points here. The information is less than 1,000 words, making it around the same size as a typical new article or viral click-bait page. From a data-driven approach, readers who are engaged with a topic tend to consistently increase their engagement, up-to about 4,000 words, then behaviours diverge. See Article length for an example with more analysis.
Readers don't have to read the entire page, the links are always at the top, and there are jumping off points during the narrative. However, if the reader does not have sufficient context prior to getting to the specification, they will absolutely struggle to interpret those documents and will navigate away. The purpose of this front page in this context is to give the reader enough context to enable them to decide if it is worth investing in the commitment to read the specification, which is a much harder task. If we were using analytics, we could measure how many navigate away from the site without reading all the front page, and how many go on to the spec, having read some, or all of the front page.
There was a problem hiding this comment.
The second point is relating to accessibility. The font weights and heights used on this page are not my selection, they are calculated mathematically within Docsy, to align to the Google style guide. I believe that this is done from a mobile-first perspective because as someone with normal, age-related loss of close vision, I can comfortably read the text using these defaults on an iPhone, but have to strain to read the smaller text on the Tekton site. Docsy doesn't provide any out-of-the-box mechanism to rebalance font sizes on desktop displays vs mobile, so we would have to attempt to build and support that if we want to have optimised sizes across all devices.
There are some hacks that we could attempt in order to override the rendering, but this would impact the accessibility to those using screen readers, as well as the mobile audience. I believe that this needs a decision as to whether accessibility, mobile-access or desktop access is the priority for the design.
There was a problem hiding this comment.
I have extended Docsy to add a CDEvents-specific block type for the landing page text. This allows us to specify a lighter font weight. I have pushed this as far as I can because it is now starting to get hard to read on mobile.
I have also added an alternate set of styles for links, for dark backgrounds. Contrast ratios are better however I intend to revisit this in a later PR to dial in the final balance.
There was a problem hiding this comment.
Sounds good to me. Accepted.
content/en/_index.html
Outdated
| <a href="https://cd.foundation/"><img src="https://raw.githubusercontent.com/cdfoundation/artwork/main/cdf/stacked/color/cdf-stacked-color.svg" width="20%"/></a> | ||
| {{< /blocks/lead >}} | ||
|
|
||
| {{< blocks/lead title="Benefits" color="white">}} |
There was a problem hiding this comment.
I do agree that a narrative could be very valuable here. But these paragraphs are maybe a bit unnecessarily long for people to not stop reading before they reach the last paragraph. I don't know how to abbreviate the text really, but an alternative could maybe be to change most of the text to be non-bold, and emphasizing the most important sub-sentences in bold instead? Kind of how Tekton does it on https://tekton.dev/
|
Cleaned up... |
|
I looked at the proposal a bit together with Mattias L today and here is some feedback:
|
|
The new font is definitely an improvement, thank you!
I think the first scrolling page should not contain extra text so that the scroll arrow is displayed:
I think it would be nice to use some visual tool to diversify more the content, like the three columns with icons, or tiles with a title or else, I'm open to suggestions. It looks like the colour schema was changed - is the change related to accessibility? |
|
From what I can see, the reactive defaults in Docsy are set up based around a 1920x1080 baseline display. It steps down as you get to a number of intermediate display sizes for different devices, and this triggers different reactive behaviour, including first miniturising the top menu (which causes the Releases menu to be hidden) and then eventually hiding the whole menu bar in the hamburger menu. The hidden Releases menu is either an intentional feature, or a Docsy bug. We could try reporting as such? I'm not seeing any obvious way to limit the text width at max resolution. This all appears to get calculated dynamically. We probably wouldn't want to reduce this in any case, since it would give up problems rendering the tables in the specification and make the white paper hard to read. |
|
@afrittoli The importance of the two example images you show above is the difference in visual hinting and how that impacts behaviour. In the original example, it looks to a new reader as if this is an empty landing page and that the first action for the reader should be to click the 'Get Started' button. This jumps you into technical documentation, unprepared. A very observant reader might press the down arrow, or scroll, but having to place arrows on a page to tell people how to read them is a fundamental failure of UI design, which places graphic design sensibilities above usability. In the revised design, we are informing the reader of a shortcut to jump out of sequence to get straight to the docs, but we are also showing that there is more to consume on this page by hinting that the text continues by scrolling. Note that for most users, scrolling is a one-handed guesture, but button-pressing requires shifting grip or using the other hand. The visual language that you are hinting at, has a different purpose. When you are looking at marketing pages for mature products, they are using a lot of graphical images to reinforce a brand image to a target market segment, by subliminal association. The customer already knows what the product is, and the intent is to reinforce them feeling good about the product during their visit. You have a very different issue. You need to attract early adopters who have a very specific problem that could be solved if this product was built. When they hit the site, you have less than 20 seconds to get them to read the first 100 words and hook their attention enough to get them to invest 2-3 minutes to explore further and establsh if this addresses their problem. If you fail to convince them that this solves an immediate problem in their field, they will move on. The only people who will get to the point of reading the spec is that tiny subset who have the problem that CDEvents mitigates. At this very early start-up stage, it is easy to fall for the vanity approach of trying to replicate a glossy sales brochure, but it's too early for that. Instead, you must apply the Continuous Delivery methodology and create experiments that engage with the early adoptors who have this problem badly enough to be willing to work with you to solve it. Your web page is an elevator pitch, not a sales brochure. |
|
The colour scheme has been adjusted to start to address accessibility issues. The blue/green combo in the logo creates severe contrast issues, so we need to use more complementary accent colours to work around this. |
Yes, if the disappeared Releases menu seems to be a Docsy bug I believe it should be reported.
|
I agree to that. And I then also think that we should not have the Docs or GitHub link buttons provided that early on the page. The documentation link is already in the top menu, to readers looking for that could easily find it without having it where "Read the Docs" is now. And the GitHub link could be moved to the top menu as well I think. |
I have raised an issue on the Docsy repo. |
Minor accessibility changes Balanced fonts and link contrast Fixed community page Removed buttons Signed-off-by: Terry Cox <[email protected]>
Agreed. I have updated and it looks better without the buttons at the top. The GitHub link is in the Community page, which I have also fixed in this PR. We need to add a contribution-guidelines.md file in the root of the spec repo (Docsy default location). |
Adds introductory narrative to landing page.
Adds Releases menu (using temporary links to spec github until post-v1.0.0 introduces historical version of this site)
Adds version number to breadcrumb bar.
Signed-off-by: Terry Cox [email protected]