CSS property reference pages - going further?

[William Bamberg]

Thanks everyone who helped improve the content and structure of CSS
property pages this weekend! I was very impressed with how much we got
done, and found it really inspiring :).

While updating some CSS property reference pages, I wondered if we could do
a better job of presenting useful info on the page above the fold: without
making users scroll.

Here are a couple of screenshots:

The MDN page for max-height: https://i.imgur.com/JS4q0U4.png
The w3schools page for max-height: https://i.imgur.com/veby74D.png

Both with the browser maximised.

Page design:
- the w3schools page has more vertical space available for content: about
410px versus 290px. In particular (and this is the bit that makes me
saddest) the very middle of the page, on MDN, is just empty space. On
w3schools the middle of the page is a syntax-highlighted example.

Content:
- the w3schools page starts with an example, which gives me some useful
info right away, but is also more visually appealing
- the MDN page loses another ~40px of vertical height by having the H2
Summary, which is always the same for every page. Then it has a good
summary, but then a table which maybe shouldn't be the first thing
presented.

Can we do better? To make things more concrete, here's an alternative MDN
page: https://i.imgur.com/Rg5txHu.png.

This makes a few changes:
- prevents the title from occupying the complete width, in the many cases
where it doesn't have to
- reduces some whitespace a bit
- removes the "Summary" heading
- pulls the "informal syntax" out of the "Syntax" section, and places it
right under the summary paragraph

I'm no designer, and I'm not advocating that we make all these changes, and
I acknowledge that there would be tricky things to think through with most
of them. It's just a mockup to see what effect making these kinds of
changes would have.

Do we think this page is better? Better enough to try to work through the
issues? Are there tests we can design to see how well different page
structures work?

Thanks!

Will

[Chris Mills]

I think this is a lot better. I never put the “Summary" title in (it’s pretty obvious what that section is, therefore it's a complete waste of space), and I think leading with the example is much more useful to web developers in general, than having the yellow box up top.

[Karl Dubost]

William,

Le 1 avr. 2015 à 02:52, William Bamberg <wbam...@mozilla.com> a écrit :
> Here are a couple of screenshots:
>
> The MDN page for max-height: https://i.imgur.com/JS4q0U4.png
> The w3schools page for max-height: https://i.imgur.com/veby74D.png

Nice! You made me curious. So I pushed a bit further.

(1.2 Mb JPEG image)
http://www.la-grange.net/2015/04/01/documentation-comparison.jpg

This is comparing
MDN, w3school, webplatform, msdn, sitepoint, blackberry, cssdog, css3com, cssportal, techonnet
The grey area is what is "below the fold"

Another metrics could be the size of the content in characters.

--
Karl Dubost, Mozilla
http://www.la-grange.net/karl/moz

[Sebastian Zartner]

I basically agree with you, Will. Unfortunately we didn't come to that
conclusion at the Hack on MDN weekend.

I'd even go a step further and restructure the general layout of the page
to make it waste less space.
I created a mockup for how I imagine this:

http://i.imgur.com/knsZ0Iq.png

If we can get rid of the horizontal restriction to 1400 pixels, this
wasting of horizontal space could even be less.
I also created a mockup for that case:

http://i.imgur.com/wtDQhlC.png

These mockups include the following changes:
*General layout changes:*

- Merged both header lines into one
- Made page heading use less vertical space in case it doesn't need it
(if the page heading is longer, the page contents will be moved down like
before)
- Shrinked vertical margins of edit buttons, breadcrumb path, page title
and sidebar

*CSS area related changes:*

- Removed 'Summary' heading (not having a strong opinion about that)
- Moved the cssbox below the 'Formal syntax'

Furthermore the sidebar could be completely hidden in case there are no
related points.

So what about that?

Sebastian

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
> Doc project Trello board: https://trello.com/b/HAhl54zz/status
>

[Jean-Yves Perrier]

Hi!

There are 3 points in discussion here:

1. Removal of Summary.
I'm all for it, I removed it from the API long time ago: it takes
valuable space and is misleading (it is isn't a "summary" of the property).

We can do it quite easily.

2. Pushing up content when there are short titles
I'm also all for it. But this need a quite important refactoring of the
CSS of the page, and there are likely some edge cases (zones, non-CSS
pages).
Justin: do you think that this is something that the MDN Council should
discuss?

We raised the other ways of winning space during the redesign in 2013
and they were refused. So I wonder what has changed since then?

3. The box.
I'm a bit annoyed to have it below the fold. It contains valuable
information (like the initial value, the meaning of the %-age or if a
property can be animated or not) and the position of this info should be
predictable to have muscle memory to be efficient.
We agreed in Berlin to trim it down, and this is something we still need
to finish.

I think we should first finish this and revisit it then.

Also I would like to see if we could find another position for it: not
necessary in the flow of the article (which would inevitably means lower
in the page). Maybe below or above the TOC? We have constrained us to
have it in the main article because this is the only place we have
direct control over it.

It could be useful to have a more thorough study about it.
Justin: do you think this is worth investigate further? If so what
should be the next steps? Involving designers?

--
Jean-Yves

--
Jean-Yves Perrier
Senior Technical Writer / Mozilla Developer Network

[Chris Mills]

> On 1 Apr 2015, at 13:07, Jean-Yves Perrier <jype...@gmail.com> wrote:
>
> Hi!
>
> There are 3 points in discussion here:
>
> 1. Removal of Summary.
> I'm all for it, I removed it from the API long time ago: it takes
> valuable space and is misleading (it is isn't a "summary" of the property).
>
> We can do it quite easily.
>
> 2. Pushing up content when there are short titles
> I'm also all for it. But this need a quite important refactoring of the
> CSS of the page, and there are likely some edge cases (zones, non-CSS
> pages).
> Justin: do you think that this is something that the MDN Council should
> discuss?
>
> We raised the other ways of winning space during the redesign in 2013
> and they were refused. So I wonder what has changed since then?
>
> 3. The box.
> I'm a bit annoyed to have it below the fold. It contains valuable
> information (like the initial value, the meaning of the %-age or if a
> property can be animated or not) and the position of this info should be
> predictable to have muscle memory to be efficient.

I too agree that it’s very valuable. I think the trouble here is that what’s best for one audience is not necessarily best for another.

Having the info box at the top is probably better for advanced CSS folks, who will more often want to check details like computed value or animatable status.

Less advanced CSS folks will more often just want to see an example that they can copy and paste first, and then worry about the deeper details later on.

I think I err in favour of having the example higher up than the info box, because I think that will be useful to more people, more of the time, even through perhaps it isn’t best for the advanced audience MDN is more traditionally associated with. But we want to branch out and because more appealing to beginners, right?

> We agreed in Berlin to trim it down, and this is something we still need
> to finish.
>
> I think we should first finish this and revisit it then.
>
> Also I would like to see if we could find another position for it: not
> necessary in the flow of the article (which would inevitably means lower
> in the page). Maybe below or above the TOC? We have constrained us to
> have it in the main article because this is the only place we have
> direct control over it.

I think having it above the TOC could work well - the TOC is definitely less important in a ref article, as the structure is generally uniform.

>
> It could be useful to have a more thorough study about it.
> Justin: do you think this is worth investigate further? If so what
> should be the next steps? Involving designers?

I think it is definitely worth testing/thinking about.

[Jean-Yves Perrier]

On 01/04/2015 13:32, Chris Mills wrote:
>> I think I err in favour of having the example higher up than the info box, because I think that will be useful to more people, more of the time, even through perhaps it isn’t best for the advanced audience MDN is more traditionally associated with. But we want to branch out and because more appealing to beginners, right?
>>
>

There is a misunderstanding here: we don't want to stop dealing with the
advanced audience on MDN, this stays our main target.

[Chris Mills]

> On 1 Apr 2015, at 13:38, Jean-Yves Perrier <jype...@gmail.com> wrote:
>
> On 01/04/2015 13:32, Chris Mills wrote:
>>> I think I err in favour of having the example higher up than the info box, because I think that will be useful to more people, more of the time, even through perhaps it isn’t best for the advanced audience MDN is more traditionally associated with. But we want to branch out and because more appealing to beginners, right?
>>>
>>
> There is a misunderstanding here: we don't want to stop dealing with the
> advanced audience on MDN, this stays our main target.

There is no misunderstanding - I understand and agree that this should stay our main focus. But there is nothing wrong with making the pages more appealing to beginners. We need to do so, if we are to turn the tide against sites like W3Schools. The number of times you hear a teacher/professor say “I recommend students to look at W3Schools because of the examples, etc."

[Jean-Yves Perrier]

Yes, this is what we already have done last week and week-end. We
decided not to move the box below.


--
"Prenez soin des minutes, les heures prendront soin d'elles-mêmes."
P.D. Stanhope (4e baron de Chesterfield, 1694-1773)

[Chris Mills]

> On 1 Apr 2015, at 13:51, Jean-Yves Perrier <jype...@gmail.com> wrote:
>
> On 01/04/2015 13:43, Chris Mills wrote:
>>> On 1 Apr 2015, at 13:38, Jean-Yves Perrier <jype...@gmail.com> wrote:
>>>
>>> On 01/04/2015 13:32, Chris Mills wrote:
>>>>> I think I err in favour of having the example higher up than the info box, because I think that will be useful to more people, more of the time, even through perhaps it isn’t best for the advanced audience MDN is more traditionally associated with. But we want to branch out and because more appealing to beginners, right?
>>>>>
>>> There is a misunderstanding here: we don't want to stop dealing with the
>>> advanced audience on MDN, this stays our main target.
>> There is no misunderstanding - I understand and agree that this should stay our main focus. But there is nothing wrong with making the pages more appealing to beginners. We need to do so, if we are to turn the tide against sites like W3Schools. The number of times you hear a teacher/professor say “I recommend students to look at W3Schools because of the examples, etc."
> Yes, this is what we already have done last week and week-end. We
> decided not to move the box below.

Right. I think we should reconsider this decision. But I guess this is why this thread is happening in the first place ;-)

[Jean-Yves Perrier]

We should first finish what has been decided. There are still a lot of
work to be done there and the result is already better for beginners
without impairing advanced users. Also I don't want to have pages with 4
different looks to coexist there.

Moving down the box means that we have to do the same for the other
similar boxes that exists: html, events, web audio. So we are moving out
of the CSS-only project and are increasing the affected pages from 600
(including a lot of non-standard properties) to more than 1000, largely
too big for Q2 (especially as the Event guide need preliminary work, the
removal of 100s of macros, that has started but won't be finished early
in the Quarter, to the best).

There are alternative placements for this box (or its content) to be
considered, but they need dev resources to be implemented, resources we
don't have and need to be secured before we can dig into these other
solutions (or we may work for nothing, which we can't afford).

We could go out of a small content area refactoring to a major redesign
at the Web site level, with preliminary UX studies, several designs to
compare and iterate, then implementation. But I'm not sure Justin and
Ali planned to give us the resources to do this now.

[Stephanie Hobson]

Hi All,

As an expert dev I often find myself picking W3Schools over MDN because I
can't remember how to spell animation or can't remember if there's a dash
in no-wrap and just want to copy and paste. I treat the two resources very
differently in my work flow right now. So I'm not against working to get
the example further up the page if that's what people want (but it sounds
like there was already a discussion of this).

But I want to remind you of two things when you are moving things around
the page:
1) Page titles have variable lengths. Maybe work with this one instead of
max-height?
https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function
2) A readable line length is 50-60 characters (
http://baymard.com/blog/line-length-readability)

Please don't sacrifice design decisions that have been carefully made
considering a wide array of factors when optimizing for a single goal.

Thanks,
Stephanie.





On Wed, Apr 1, 2015 at 6:48 AM, Jean-Yves Perrier <jype...@gmail.com>

[Stephanie Hobson]

As for hiding the Summary, I think it is an important part of the document
structure but we could add a rule to the stylesheets, hiding the heading
everywhere if it is the first thing in the article. This would save you
work and leave the heading there for semantics.

I see problems with this in that:
- it becomes less likely that people will add the heading to new pages,
since they won't see it on existing ones
- it is possible there are headings that are not "summary"

Thanks,
Stephanie.




On Wed, Apr 1, 2015 at 9:09 AM, Stephanie Hobson <sho...@mozilla.com>
wrote:

[Thierry Régagnon]

Le 01/04/2015 18:09, Stephanie Hobson a écrit :
> 2) A readable line length is 50-60 characters (
> http://baymard.com/blog/line-length-readability)

Yes!

Thanks for creating mockups Sebastian, but I am with Stephanie on this
one. ;) We should not removed the max-width as it will degrade readability.

Aside from this point, I like the reduced header in Sebastian first
mockup. I would not reduce the margins and the white-space (again for
readability), but I think the header with the main nav is secondary for
people coming on the reference articles.

--
Thierry Régagnon

[Eric Shepherd (Sheppy)]

These conversations are always interesting: I personally find long line lengths easier to read, because I can see more at once. But I read unusually fast, taking in a line at a time without having to do a lot of word by word scanning, so the length of a line doesn't affect me much.
That useless remark aside, I think we are narrowing in on a key problem: I think it's increasingly clear that there are times when usability of a documentation page and traditionally good design standards don't necessarily mesh. Compromises may have to be made.

Eric Shepherd
Senior Technical Writer
Mozilla

[Sebastian Zartner]

On 2 April 2015 at 04:50, Eric Shepherd (Sheppy) <eshe...@mozilla.com>
wrote:

> These conversations are always interesting: I personally find long line
> lengths easier to read, because I can see more at once. But I read
> unusually fast, taking in a line at a time without having to do a lot of
> word by word scanning, so the length of a line doesn't affect me much.
>

FWIW, I'm more like the opposite kind of reader. I'm reading relatively
slowly to understand the meaning of a paragraph, sometimes for checking
single words for correctness. Non-the-less I usually don't have a problem
to read long lines.
Anyway, Stephanie's point is absolutely understandable. So removing the
horizontal restriction may not be the best solution.

The main point behind that idea was to make better use of the horizontal
space, though, especially on wide screens, which I believe is still valid.

Sebastian

[William Bamberg]

Thanks for such a lively discussion.

First, I don't think any of this invalidates the work we did in Berlin. It
builds on it.

Jean-Yves: I basically agree with your response separating the proposal
into 3 pieces (although to emphasize, I'm not necessarily pushing these
particular pieces, just trying to experiment with ways to make the docs
more usable).

> 1. Removal of Summary.

> I'm all for it, I removed it from the API long time ago: it takes
> valuable space and is misleading (it is isn't a "summary" of the
property).
>
> We can do it quite easily.

This seems like the easiest and least controversial piece, although it
would affect the devtools piece, so I'd like to get it nailed down sooner
rather than later.

Stephanie: I'd like to understand a bit better your point about needing it
for document structure:

> I think it is an important part of the document
> structure but we could add a rule to the stylesheets, hiding the heading
> everywhere if it is the first thing in the article. This would save you
> work and leave the heading there for semantics.

What are we using it for, specifically? It seems that we don't think it's
useful structure for readers of these pages. Do you mean, things like the
devtools tooltip using it to find specific bits of the page?
For that, it seems unfortunate that we have to insert headings not for the
benefit of readers, but for the benefit of the machines.

> I see problems with this in that:
> - it becomes less likely that people will add the heading to new pages,
> since they won't see it on existing ones
> - it is possible there are headings that are not "summary"

I agree, this doesn't seem like a good approach.

> 2. Pushing up content when there are short titles

Jean-Yves:

> I'm also all for it. But this need a quite important refactoring of the
> CSS of the page, and there are likely some edge cases (zones, non-CSS
> pages).
> Justin: do you think that this is something that the MDN Council should
> discuss?
>
> We raised the other ways of winning space during the redesign in 2013
> and they were refused. So I wonder what has changed since then?

Yes, this keeps coming back, and yes, it would be a complicated change.

Stephanie:

> But I want to remind you of two things when you are moving things around
> the page:
> 1) Page titles have variable lengths. Maybe work with this one instead of
> max-height?
>
https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function

Yes: I don't want to suggest that this is an easy thing to do and that
there wouldn't be hard cases. And maybe overall the current design is
optimal. But most actual CSS properties _would_ fit in the left column, so
optimizing for the ones that wouldn't gives us this donut effect in the
page a lot of the time.

> 2) A readable line length is 50-60 characters (
> http://baymard.com/blog/line-length-readability)

Agree about line length.

> Please don't sacrifice design decisions that have been carefully made
> considering a wide array of factors when optimizing for a single goal.

I understand, and really don't want to give the impression that I think I
can do better than people who actually have the professional skills to do
this, and who have spent a lot of time perfecting it. If this page layout
is really the best we can do, then it is. But I think it is reasonable to
raise the question.

JYP:

> 3. The box.
> I'm a bit annoyed to have it below the fold. It contains valuable
> information (like the initial value, the meaning of the %-age or if a
> property can be animated or not) and the position of this info should
be
> predictable to have muscle memory to be efficient.

> We agreed in Berlin to trim it down, and this is something we still
need
> to finish.
>
> I think we should first finish this and revisit it then.

Sounds good. I agree that the box, especially after redesign, also contains
important information.

Will

[Stephanie Hobson]

> Stephanie: I'd like to understand a bit better your point about needing it
> for document structure
>

The source order for the page includes the Table of Contents between the
article title and the document summary. If we remove the heading there
won't be a landmark for screen reader users to use to skip past the Table
of Contents and if they're navigating the page by headings there's no
indication of where the content starts.

S.

On Wed, Apr 8, 2015 at 10:26 AM, William Bamberg <wbam...@mozilla.com>
wrote:

[Justin Crawford]

>
> It could be useful to have a more thorough study about it.
> Justin: do you think this is worth investigate further? If so what
> should be the next steps? Involving designers?

Regarding questions about what information should go where:
* In recent conversations with extremely advanced developers, I have heard,
"We skip straight to the syntax and the examples."
* In recent conversations with developers just learning how to code, I have
heard, "I want to see how to use it."

Of course they are just anecdotes. Both seem to advocate for changing what
comes first on the page. I think there are two ways to go with this:
a) We could make a bunch of changes and measure whether they have a
positive effect. We're already making those changes -- have we devised a
way to measure it? Helpfulness would work, but it's not ready now.
b) We could run some variation on a card-sorting exercise and ask some
typical users to help organize the page for us. We're not primed for doing
this right now, but I sure wish we could do more of this.

Regarding questions about how to compress the height to get more
information into the initial viewport:
Yes, I think this is something we would undertake with designers. I wasn't
present when the 2013 conversations about recapturing space took place --
can someone link me to them?

Comparisons with those other documentation sites are instructive, but they
just don't have as many controls as we have. Some allow you to login; some
to edit; some to subscribe; but the number of features we have requires a
ton of instrumentation. Another reason that changes here need design.

Mitigating factors:
* When I load w3schools with Adblock Plus disabled, I get an annoying
banner ad where MDN has large header elements. I prefer the large header
elements.
* The "Soapbox" at the top of MDN may seem like a perpetual element lately
thanks to a certain product manager *cough* using it to run surveys, but it
shouldn't be. That's 38 pixels we can shave off sometimes.


Justin Crawford
Product Manager, MDN
hoos...@mozilla.com

On Wed, Apr 8, 2015 at 12:03 PM, Stephanie Hobson <sho...@mozilla.com>
wrote: