296903 - Clean up organization of Tabbed Browsing

Status: RESOLVED FIXED

(Firefox Graveyard :: Help Documentation, defect)

Description

[Jeff Walden (gone starting June 8)]

The ordering's just odd.  We've got equivalent-level subheadings corresponding
to different-level <hX/> elements, and we seem to be randomly choosing which
subheadings to expose as well.

Once bug 295902 is fixed, I'm leaning toward roughly the following, and I'd like
feedback before I start working on a patch (which has to wait on bug 295902
anyway).  First, eliminate Using Tabbed Browsing as a section.  It adds nothing
to the document that wouldn't be better added in the document preface before the
In this section: box.  That paragraph shouldn't get too long if the edit's done
right.  Second, we move the <h3/> elements to <h2/> and so on to keep the header
hierarchy correct.  Third, we remove the keyboard shortcuts and redirect links
to the tabs section of shortcuts.xhtml.  The shortcuts docs don't need to be
duplicated between the two docs, and the table's quicker and easier to skim. 
Finally, we add each subheading to the toc and make sure all index/toc links
work correctly again to wrap up the changes.

It would be nice, tho not imperative, to fix this for 1.1 to make the document
less of a hodgepodge of information, especially because there's not much new
content to write or existing content to combine.

Comment 1

[Steffen Wilberg]

I completely agree.

Comment 2

[Jeff Walden (gone starting June 8)]

Attachment: First stab

This patch is very much incomplete still.  I haven't touched RDF yet,
whitespace and alignment are out of whack, and the reorganization is up for
debate.  That said, I more or less like what I have here content-wise.

On the topic of small things, I didn't end the intro paragraph with a, "This
section describes..." note.  I don't really think it's needed here, and I
couldn't come up with one that wouldn't just duplicate what had already been
said.

The big, unexpected change I made was to consolidate the "miscellaneous" tips
together so they wouldn't eat up header space (which would be an issue for the
in-page toc and the UI toc).  I had a feeling this might be needed, but I
wasn't actually certain until I'd had time to look at it with changes applied.

One change I'm considering is adding to the tips/tricks section a tip on
organizing web pages by subject into different windows of tabs.  This is
definitely one of the more useful ways to use tabs, and I think it's worth
highlighting.  I haven't given much thought to it, tho, because writing
something that's coherent and concise will be difficult.  Anyway, that's
probably something that doesn't need fixing quite yet, so it'll probably be
punted to 1.9.

Apparently they're wrapping up things for the next beta, so approvals are going
to be much harder to get soon; time's starting to run short, but overall we're
in decent shape.  I'll have to punt some things to 1.5, but it shouldn't be a
big deal.

Comment 3

[Steffen Wilberg]

Comment on attachment 187751 [details] [diff] [review]
First stab

"surf the Internet"?
"Browse the Web" sounds better.

>+<h2 id="customizing">Customizing Tabbed Browsing</h2>
>+  <p>To change tabbed browsing &pref.plural; select &pref.menuPath; and open the
>+    <em>Tabs</em> panel. Descriptions of the &pref.plural; there can be found
>+    under <a href="prefs.xhtml#tabs_options">Tabbed Browsing</a>.</p>
Uh, this was called "Tabbed Browsing" in 1.0, but it's now the Tabs panel.
Let's make "Tabs panel" link to the Tabs options and remove the second
sentence.

>+  <dt id="home_page_as_tabs">Home Page as Tabs</dt>
>+  <dd>Instead of using only one web page as your homepage, you can make your home
>     page a set of tabs. Select your favorite web sites and open them in tabs in
>     a single window. Select &pref.menuPath; and open the <em>General</em> panel.
We could make "General panel" link to the General panel doc as well.

r=me with index and toc fixed as well.

Comment 4

[Jeff Walden (gone starting June 8)]

Attachment: Final patch

Okay, I finished cleaning it up now.  Formatting is back to standard, and I
changed the index/toc links now.  I also addressed the nits from the previous
review.

For the approver: this patch will make our current tabbed browsing
documentation a good bit better organized.

Comment 5

[Steffen Wilberg]

Comment on attachment 187910 [details] [diff] [review]
Final patch

>               <rdf:li><rdf:Description ID="prefs-tabs" nc:name="Tabs Options" nc:link="prefs.xhtml#tabs_options"/></rdf:li>
Looks like this is my mistake. We've got ID="prefs-tabs" twice in the index.
The first one rules, which has the nc:name="Tabs", so in T->Tabbed Browsing, it
says "Tabs" instead of "Tabs Options", as defined here. Please change this ID
to "tabbed-browsing-prefs".

Comment 6

[Jeff Walden [:Waldo]]

(In reply to comment #5)
> We've got ID="prefs-tabs" twice in the index. The first one rules, which has the
> nc:name="Tabs", so in T->Tabbed Browsing, it says "Tabs" instead of "Tabs
> Options", as defined here. Please change this ID to "tabbed-browsing-prefs".

Done, and nice catch!  /me blames the RDF parser for not bailing on us when it
detected the error.

Patch checked into source, marking FIXED.  The tips/tricks addition I briefly
mentioned can wait for later if we decide to do it.