285035 - Help Documentation should look more like the Mozilla website

Status: RESOLVED FIXED

(Firefox Graveyard :: Help Documentation, enhancement)

Description

[R.J. Keller]

Currently, the Help Documentation has its own look. That look is ok, but we
should really make things look more like the mozilla.org website, like maybe
including a logo and using a similar font (which looks much more readable).

Patch and screenshot coming up.

Comment 1

[R.J. Keller]

Attachment: Screenshot

This is the kind of look that I'm thinking of. Adding the logo and using
similar fonts. Also notice the addition of mozilla.org-style borders to h1, h2,
and h3.

Comment 2

[R.J. Keller]

Attachment: Patch - adds m.o look and table enhancements

Here's the patch. Exact same changes used to get the screenshot I just
attached.

Comment 3

[Jeff Walden (gone starting June 8)]

Comment on attachment 176501 [details] [diff] [review]
Patch - adds m.o look and table enhancements

>+
>+<div id="container">
>+<div id="header">
>+<h1><a href="#" accesskey="1">Mozilla</a></h1>
>+</div>
>+</div>
>+

Why is this header in a link?  The reason it was in a link on mozilla.org was
because it pointed to the front page.  There's no front page for Help, so
you've changed the link to point to the current page.  However, if we're
offline when the Help content's loaded, we won't get the styling for this. 
Consequently, every page will have "Mozilla" as a headline with a link that
goes precisely nowhere.  There may be other offline issues to consider here,
too -- what does the content look like when it's offline with this patch
applied?

> @import url('chrome://help/content/platformClasses.css');
>+@import url('http://www.mozilla.org/css/cavendish/content.css');
>+@import url('http://www.mozilla.org/css/cavendish/template.css');
>+@import url('http://www.mozilla.org/css/base/content.css');
>+@import url('http://www.mozilla.org/css/base/template.css');

These links go directly to the CSS files mozilla.org uses.  mozilla.org's theme
has changed before, tho, and it could very easily change again.  If we do end
up doing this, the way it'll work is that we create
http://www.mozilla.org/projects/firefox/help/version/helpLayout.css (name is
subject to change), which will include the lines above.  Then we can keep
things looking good even if mozilla.org layout changes.

Also, have you talked to the visual id team about this?  I happen to think it's
a good idea, but I'd rather have real design people give some feedback on this
idea.  I just CC'd Kevin Gerich, so hopefully he can give some comments on
these changes.

So, for now, r- until the above issues are fixed...

Comment 4

[R.J. Keller]

(In reply to comment #3)
> (From update of attachment 176501 [details] [diff] [review] [edit])
> >+
> >+<div id="container">
> >+<div id="header">
> >+<h1><a href="#" accesskey="1">Mozilla</a></h1>
> >+</div>
> >+</div>
> >+
> 
> Why is this header in a link?  The reason it was in a link on mozilla.org was
> because it pointed to the front page.  There's no front page for Help, so
> you've changed the link to point to the current page.  However, if we're
> offline when the Help content's loaded, we won't get the styling for this. 
> Consequently, every page will have "Mozilla" as a headline with a link that
> goes precisely nowhere.  There may be other offline issues to consider here,
> too -- what does the content look like when it's offline with this patch
> applied?

The CSS required the hyperlink. I tried removing it and it broke everything.

Offline viewing is the issue. Maybe I should just dump most of the m.o CSS into
helpFileLayout.css? That'd get around the problem but might create some app
bloat (since the mozilla.org logo would need to be built).

> 
> > @import url('chrome://help/content/platformClasses.css');
> >+@import url('http://www.mozilla.org/css/cavendish/content.css');
> >+@import url('http://www.mozilla.org/css/cavendish/template.css');
> >+@import url('http://www.mozilla.org/css/base/content.css');
> >+@import url('http://www.mozilla.org/css/base/template.css');
> 
> These links go directly to the CSS files mozilla.org uses.  mozilla.org's theme
> has changed before, tho, and it could very easily change again.  If we do end
> up doing this, the way it'll work is that we create
> http://www.mozilla.org/projects/firefox/help/version/helpLayout.css (name is
> subject to change), which will include the lines above.  Then we can keep
> things looking good even if mozilla.org layout changes.
> 
> Also, have you talked to the visual id team about this?  I happen to think it's
> a good idea, but I'd rather have real design people give some feedback on this
> idea.  I just CC'd Kevin Gerich, so hopefully he can give some comments on
> these changes.

well, since the Visual Identity team made the mozilla.org site, I'm sure they'd
approve of it over the previous layout which they didn't make.

Comment 5

[Kevin Gerich]

Excellent idea about having the help content styles harmonize with the
Mozilla.org website styles. I do think that the Mozilla.org masthead belongs
only on the welcome page though, not all content pages, and I'd like to see a
Firefox masthead, not Mozilla.org. I'm CCing Steven Garrity who will probably
have ideas about creating a portable Cavendish.

Would you like a new web link image?

Comment 6

[Steven Garrity [:sgarrity]]

I don't think the help really has to be tied into the visual style of the
Mozilla.org website. Maybe we could just make a stripped-down version of
http://www.mozilla.org/css/cavendish/content.css which provides the basic
body/header font styles.

I'm not sure the help should have a title graphic like that - I think we'd be
better off just adopting the basic test styles from
http://www.mozilla.org/css/cavendish/content.css (and in a separate file, like
Jeff Walden suggests).

Is there an existing CSS file for the help? I don't mind taking a shot at
applying the Cavendish style to it.

Comment 7

[R.J. Keller]

Attachment: Patch - w/ Jeff and Stevens comments

(In reply to comment #6)
> I don't think the help really has to be tied into the visual style of the
> Mozilla.org website. Maybe we could just make a stripped-down version of
> http://www.mozilla.org/css/cavendish/content.css which provides the basic
> body/header font styles.
> 
> I'm not sure the help should have a title graphic like that - I think we'd be

> better off just adopting the basic test styles from
> http://www.mozilla.org/css/cavendish/content.css (and in a separate file,
like
> Jeff Walden suggests).
> 
> Is there an existing CSS file for the help? I don't mind taking a shot at
> applying the Cavendish style to it.

One step ahead of you :). Attached is the patch with most mozilla.org CSS
merged in and without the mozilla.org logo as Jeff suggested. I recommend you
reconsider the logo though because it adds a nice flow to the viewer.

Screenshot coming up.

Comment 8

[R.J. Keller]

Attachment: screenshot

Comment 9

[Steven Garrity [:sgarrity]]

Looks pretty good - If there was a need for any kind of more visual aspects, I
think something Firefox related would make more sense than the Mozilla.org
header stuff.

Also, a quick note: I think the grey box with the "In This Section" text would
look better if it were a bit lighter - maybe a background of #EEE and a border
of #CCC

Comment 10

[R.J. Keller]

Comment on attachment 176597 [details] [diff] [review]
Patch - w/ Jeff and Stevens comments

Sounds good! Jeff can you review this plus the border change Steven mentioned.

Comment 11

[Jeff Walden (gone starting June 8)]

Comment on attachment 176597 [details] [diff] [review]
Patch - w/ Jeff and Stevens comments

>+body, td, th, input {
>+  font-family: verdana, sans-serif;
>+  font-size: x-small;
>+  voice-family: "\"}\"";
>+  voice-family: inherit;
>+  font-size: small;
>+}

Steven, Kevin, "voice-family" is an IE hack, isn't it?	What's the way to make
the CSS semantically correct and hack-free?

>+input[type="submit"] {
>+	font-weight: bold;
>+}

There are no <input> elements in Help docs, nor should there ever be any. 
Please remove this.

>+code {
>+  white-space: nowrap;
>+}

Please remove this.  It isn't necessary because we shouldn't have instances of
code (or code-like things) in Help documentation.  However, for some completely
insane reason we do have an instance of this:

http://lxr.mozilla.org/mozilla/source/browser/components/help/locale/en-US/pref
s.xhtml#80

If you look, you can see that it's a bogus use; the sentence itself doesn't
even make any sense.  Please completely remove the sentence containing the
<code> element and move the closing </li> up accordingly.

Regarding the color change Steven suggested, I tested it and it's a clear
improvement.

Aside from the aforementioned trivial issues, this patch is good to go.  For
now, tho, r- until we get the first issue sorted out and tweak the patch to
make the other mentioned changes.

Comment 12

[Steven Garrity [:sgarrity]]

Jeff: Yes, the voice-family thing is an IE hack that isn't necessary in Firefox
help. You can replace these lines:

>+  font-size: x-small;
>+  voice-family: "\"}\"";
>+  voice-family: inherit;
>+  font-size: small;

with just the last line therein:

>+  font-size: small;

There will be no visual change in Firefox.

Comment 13

[R.J. Keller]

Attachment: Patch v2

(In reply to comment #11)
> If you look, you can see that it's a bogus use; the sentence itself doesn't
> even make any sense.	Please completely remove the sentence containing the
> <code> element and move the closing </li> up accordingly.

Jeff, the purpose of this bug is to make better Help CSS, not clean up the help
docs.

Tell me if the proposed changes in this patch are good.

Comment 14

[Jeff Walden (gone starting June 8)]

Comment on attachment 176718 [details] [diff] [review]
Patch v2

The proposed changes in the patch are indeed good.  There's just one little
problem that I should have brought up earlier but didn't notice until now:
you're not changing the equivalent CSS for Help on Macs.  Please patch
toolkit/themes/pinstripe/help/helpFileLayout.css as well.

Comment 15

[R.J. Keller]

Comment on attachment 176718 [details] [diff] [review]
Patch v2

ok, with those changes is it review+?

Comment 16

[Jeff Walden [:Waldo]]

Comment on attachment 176718 [details] [diff] [review]
Patch v2

Yep, things look okay.

Comment 17

[R.J. Keller]

Fix checked in.

Comment 18

[Jeff Walden (gone starting June 8)]

For the record, the color changes for the contents boxes on all the pages were
forgotten in what was checked into source.  I just checked in the fix.