Best practices for support documents: Draft1
Chris Ilias
there is a computer literacy barrier that we need to overcome, when
writing Firefox support articles. Our target reader is "mom." Typically,
"mom" does not know how to use about:config, or add a toolbar button,
without instruction. This means each article should not only provide
answers, but instructions.
It's amazing how some users can misinterpret instructions; so when
describing actions, try to word it in a way that is brief, yet *cannot
be misinterpreted* (words are expensive).
The word "user" itself is a technical term. Try to avoid phrases, like
"If a user has lost his bookmarks." Word your sentences, as if you are
speaking to the user, like "If you've lost your bookmarks..."
The title of the article describes the question being asked or the
problem being enquired about.
Good: Toolbar keeps resetting
Bad: corrupt localstore.rdf
Give a brief (one paragraph max.) summary of the cause of the problem,
and what is being done (in the article) to fix it. This is your
introduction. There's no need to name it as such (or "Background").
Users only need one answer to their question. There are cases in which
there is more than one way of accomplishing a task. In such instances,
try pick the most user-friendly method. In general, having a graphical
user-interface (menus, check-boxes, buttons, etc.) should be preferred:
If you can accomplish the task in the UI (e.g. Options panel), use that
method.
If there is no UI to accomplish the task, but there is an extension that
adds a UI for accomplishing the task, suggest the extension.
If there is no UI to accomplish the task, and no extension that provides
a UI, suggest using about:config, instead of user.js (unless
about:config will not do).
If none of the above are possible, there's usually one method of
accomplishing a task anyway. :-)
When providing step by step instructions, use a numbered list, rather
than bullets.
When creating a troubleshooting document, that presents multiple
solutions, based on the success or failure of a previous suggestion,
[still in discussion].
Instructions for practises which breach net etiquette, should make a
note of it, not make the user feel like a sinful criminal. :-)
_Multimedia_
Support multimedia needs to present Firefox in its most familiar form,
which means using as many default settings as possible. Given that most
non-technical users are on Windows, multimedia showing Firefox in
Windows is preferred over multimedia showing Firefox on Mac or Linux,
unless there's a need to be specific. If the you (contributor) don't
have Windows, that's fine; but if there's a chance to switch it to a
Windows version, take it.
* _Screenshots_
Don't be shy about including screenshots. Try to include a
screenshot(s) that will help clear any potential misunderstandings of
the article text.
* Crop what is needed, but make sure the cropped image is still
identifiable. If you need to create an image of the full screen, use a
resolution of 800x600 (just so the image doesn't take a lot of space,
without need).
* When highlighting sections, draw red lines around the section.
Good: <http://images.ilias.ca/tb-searchbar.png>
Bad: <http://images.ilias.ca/tb2-searchbar.png>
* If it doesn't make the image unreadable, decrease the size to 75%
* save for web, in PNG24 format
* _Videos_
* Provide a text version for those without hi-speed
* If there's no need for a voiceover, don't bother (saves on video
file size)
* Flash format is preferred
--
Chris Ilias <http://ilias.ca>
List-owner: support-firefox, support-thunderbird, test-multimedia
Jason Barnabe (np)
> We want Firefox Support to be usable by most Firefox users, which means
> there is a computer literacy barrier that we need to overcome, when
> writing Firefox support articles. Our target reader is "mom." Typically,
> "mom" does not know how to use about:config, or add a toolbar button,
> without instruction. This means each article should not only provide
> answers, but instructions.
One thing about "mom" is that she'll probably be on Windows, while we
still want to include Linux and Mac info.
We could use some info on "mom"'s setup.
-Default profile location
-Installer build (or from the software repository if on Linux)
> Users only need one answer to their question. There are cases in which
> there is more than one way of accomplishing a task. In such instances,
> try pick the most user-friendly method. In general, having a graphical
> user-interface (menus, check-boxes, buttons, etc.) should be preferred:
> If you can accomplish the task in the UI (e.g. Options panel), use that
> method.
> If there is no UI to accomplish the task, but there is an extension that
> adds a UI for accomplishing the task, suggest the extension.
> If there is no UI to accomplish the task, and no extension that provides
> a UI, suggest using about:config, instead of user.js (unless
> about:config will not do).
> If none of the above are possible, there's usually one method of
> accomplishing a task anyway. :-)
This could be trimmed down and made more understandable by just making
it a list from most preferred to least preferred.
> When providing step by step instructions, use a numbered list, rather
> than bullets.
Also, include the user-facing results of each step. For example, "Choose
the Firefox (Safe mode) menu option. A dialog will appear."
> Support multimedia needs to present Firefox in its most familiar form,
> which means using as many default settings as possible. Given that most
> non-technical users are on Windows, multimedia showing Firefox in
> Windows is preferred over multimedia showing Firefox on Mac or Linux,
> unless there's a need to be specific. If the you (contributor) don't
> have Windows, that's fine; but if there's a chance to switch it to a
> Windows version, take it.
If we have the capability to provide different articles or different
views for different OSes, this should be tweaked.
> Don't be shy about including screenshots. Try to include a
> screenshot(s) that will help clear any potential misunderstandings of
> the article text.
Are we concerned that the user may confuse screenshots of dialogs with
the dialogs themselves?
Chris Ilias
> We want Firefox Support to be usable by most Firefox users, which means
> there is a computer literacy barrier that we need to overcome, when
> writing Firefox support articles. Our target reader is "mom." Typically,
> "mom" does not know how to use about:config, or add a toolbar button,
> without instruction. This means each article should not only provide
> answers, but instructions.
Before I forget, I should add something about using instructions for
menu paths (ie. Instead of "Got to Tools>Options...", say "At the top of
the Firefox window, click on the Tools menu, and select Options...")
David Tenser
> If you can accomplish the task in the UI (e.g. Options panel), use that
> method.
> If there is no UI to accomplish the task, but there is an extension that
> adds a UI for accomplishing the task, suggest the extension.
I'm not convinced this is the right way to go, for a couple of reasons:
1. Do we want to officially recommend extensions like this, and
regularly verify that they still work properly for the suggested purpose?
2. Is it really easier for a user to navigate to a.m.o, install an
extension, restart Firefox, and then perform the suggested actions?
Just wanted to share my point of view.
-- David
Kevin Brosnan
> support-planning mailing list
> support-...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/support-planning
>
I think this should be evaluated on a case by case basis. Extensions
that are recommended should solve that one issue with a minimal number
of additional features. The suggested extension should not be
sandboxed. However if there is a sandboxed extension that looks
promising it should be evaluated and then moved out of the sandbox.
Good: Suggesting FireFTP to allow login to password protected* or
active ftp servers
Bad: Suggesting Tab Mix Plus to change the close buttons to the 1.5 style.
* I know us...@ftp.example.org works but our target audience is likely
to forget this little bit of trivia.
Kevin Brosnan
Majken Connor
and warn people of conflicts. I think we want to list extensions
after listing about:config solutions, and at the same level of making
profile changes by hand. If we're talking about userChrome changes,
of course extensions are better, but for things like backing up the
profile, I think most users can handle the instructions to do it by
hand.
-Majken
On 7/5/07, Kevin Brosnan <kbro...@gmail.com> wrote:
> On 7/5/07, David Tenser <djst.m...@gmail.com> wrote:
Chris Ilias
> Another problem is we'd have to track all the extensions we recommend
> and warn people of conflicts. I think we want to list extensions
> after listing about:config solutions, and at the same level of making
> profile changes by hand. If we're talking about userChrome changes,
> of course extensions are better, but for things like backing up the
> profile, I think most users can handle the instructions to do it by
> hand.
Okay, so order of preference is:
1. Distributed UI
2. about:config
3. Extension
4. User script
Is good?
David McRitchie
> Chris Ilias wrote:
> > If there is no UI to accomplish the task, but there is an extension that
> > adds a UI for accomplishing the task, suggest the extension.
>
> I'm not convinced this is the right way to go, for a couple of reasons:
>
> 1. Do we want to officially recommend extensions like this, and
> regularly verify that they still work properly for the suggested purpose?
>
> 2. Is it really easier for a user to navigate to a.m.o, install an
> extension, restart Firefox, and then perform the suggested actions?
>
> Just wanted to share my point of view.
Thanks David, and I certainly share your point of view, and I
have a much better appreciation of Firefox because of clearly
written simple user changes that do exactly what I want without
bloated themes and extensions for simple things. Thanks for doc.
--
David McRitchie, Firefox Customizations in pictures
http://www.mvps.org/dmcritchie/firefox/pictures.htm
Jason Barnabe (np)
For the general case of "set it and forget it" pref changes, that's
good. If it's something that people would want to change often, it'd
be different. I'd stick with that order and add a clarification.
Chris Ilias
there is a computer literacy barrier that we need to overcome, when
instruction. This means each article should not only provide answers,
default values. In general, try to write articles in such a way, that
your mom would understand.
It's amazing how some users can misinterpret instructions; so when
describing actions, try to word it in a way that is brief, yet *cannot
be misinterpreted* (words are expensive).
The word "user" itself is a technical term. Try to avoid phrases, like
"If a user has lost his bookmarks." Word your sentences, as if you are
speaking to the user, like "If you've lost your bookmarks..."
The title of the article describes the question being asked or the
problem being enquired about.
Good: Toolbar keeps resetting
Bad: corrupt localstore.rdf
Give a brief (one paragraph max.) summary of the cause of the problem,
and what is being done (in the article) to fix it. This is your
introduction. There's no need to name it as such (or "Background").
Users only need one answer to their question. There are cases in which
there is more than one way of accomplishing a task. In such instances,
try pick the most user-friendly method. In general, the order of
preference is:
1. The graphical user-interface (menus, check-boxes, buttons, etc.)
distributed with Firefox.
2. If it's a preference, that the user is likely only to change once,
use about the about:config method
3. Extension
4. User script (user.js, userChrome.css, userContent.css, etc.)
If none of the above are possible, there's usually one method of
accomplishing a task anyway. :-)
When providing step by step instructions, use a numbered list, rather
than bullets.
Include expected results, when giving instructions (e.g. Choose the
Firefox (Safe mode) menu option. *A dialog will appear.*)
Instructions directing a user to an item in the user-interface should be
full sentences.
Good: At the top of the Firefox window, click on the Tools menu, and
select Options..."
Bad: Go to Tools > Options...
Chris Ilias
Outline of changes and feedback from Draft1:
- I added a note about mom using the default settings, but I don't think
mention of 'mom uses windows' would apply; because of the versions plugin.
- I added a note about including expected results (e.g "A dialog will
appear.")
- We'll probably remove the item about doing multimedia in Windows; but
until we have a more vivid vision of the how-to articles, I'm keeping it in.
- I didn't add anything in regards confusing screenshots with actual
windows. If their scaled to 75%, I don't think it will be a problem.
- I added a note about UI paths being in full sentences
- I changed the order of preferred methods, and tried to trim it down,
to a numbered list.
Chris Ilias
> Is there anything which can be accomplished with user.js which /can't/
> be accomplished via about:config?
Yup. about:config will not work in case, which the preference value
includes a line break (e.g. \n).
> If the target audience is my own
> mother, telling her to edit user.js would only result in crying.
>
> In cases which land at (4), if it's userChrome.css or userContent.css, I
> really think it's worth considering sending the user (sorry, I mean
> sending you ;) to get the Stylish extension. Again, trying to edit
> those files would make my mother cry (literally), but I think she could
> use Stylish, especially since once it's installed she could just click
> on a provided css snippet to install it.
I think that's a great idea; but I've just tried stylish (on Mac), and
using Tools-->Stylish-->Manage_Styles doesn't open anything (no messages
in error console either). The icon in the bottom right still works.
Here's a video of it:
<http://ilias.ca/flashback/iShowU-Capture.mov> [32.8MB]
Sorry about the file size. The screen recorder I use on Windows isn't
available for Mac; so I'm testing out screen recorders for Mac.
Chris Ilias
> In <news:Go2dnQZV2sXzOwzb...@mozilla.org>,
> Chris Ilias <n...@ilias.ca> wrote:
>
>> * _Screenshots_
>> Don't be shy about including screenshots. Try to include a
>> screenshot(s) that will help clear any potential misunderstandings of
>> the article text.
>
> screenshots.
There is a note about that underneath the Multimedia heading (with
Screenshots, and Videos being sub-headings of MM). Perhaps it would be
less 'missable' if I just put the MM info underneath both Screenshots
and Videos (thus saying it twice).
>> * If it doesn't make the image unreadable, decrease the size to 75%
>> * save for web, in PNG24 format
>
> PNG24 is PNG with 24-bit color depth?
I guess so. :-[
I should just generalize that to PNG.
Jason Barnabe (np)
> In <news:z7WdnRskE5OXIw_b...@mozilla.org>,
>
> Chris Ilias <n...@ilias.ca> wrote:
> >> In cases which land at (4), if it's userChrome.css or
> >> userContent.css, I really think it's worth considering sending the
> >> user (sorry, I mean sending you ;) to get the Stylish extension.
> >> Again, trying to edit those files would make my mother cry
> >> (literally), but I think she could use Stylish, especially since
> >> once it's installed she could just click on a provided css snippet
> >> to install it.
>
> >I think that's a great idea; but I've just tried stylish (on Mac), and
> >using Tools-->Stylish-->Manage_Styles doesn't open anything (no
> >messages in error console either). The icon in the bottom right still
> >works.
>
> Fx with a fresh profile, just after installing Stylish 0.5.2 and adding
> its icon to the toolbar. This is under GNU/Linux.
> <http://remarqs.net/misc/stylish-nonmenu.png>
This is getting a little far away from the discussion at hand. Anyone
who has trouble can discuss with me at userstyles.org/forum
Chris Ilias
Actually, I was just citing the problem as a reason not suggest it. :-)
Chris Ilias
there is a computer literacy barrier that we need to overcome, when
instruction. This means each article should not only provide answers,
default values. In general, try to write articles in such a way, that
your mom would understand.
It's amazing how some users can misinterpret instructions; so when
describing actions, try to word it in a way that is brief, yet *cannot
be misinterpreted* (words are expensive).
The word "user" itself is a technical term. Try to avoid phrases, like
"If a user has lost his bookmarks." Word your sentences, as if you are
speaking to the user, like "If you've lost your bookmarks..."
The title of the article describes the question being asked or the
problem being enquired about.
Good: Toolbar keeps resetting
Bad: corrupt localstore.rdf
Give a brief (one paragraph max.) summary of the cause of the problem,
and what is being done (in the article) to fix it. This is your
introduction. There's no need to name it as such (or "Background").
Users only need one answer to their question. There are cases in which
there is more than one way of accomplishing a task. In such instances,
try pick the most user-friendly method. In general, the order of
preference is:
1. The graphical user-interface (menus, check-boxes, buttons, etc.)
distributed with Firefox.
2. If it's a preference, that the user is likely only to change once,
use about the about:config method
3. Extension
4. User script (user.js, userChrome.css, userContent.css, etc.)
If none of the above are possible, there's usually one method of
accomplishing a task anyway. :-)
When providing step by step instructions, use a numbered list, rather
than bullets.
Include expected results, when giving instructions (e.g. Choose the
Firefox (Safe mode) menu option. *A dialog will appear.*)
Instructions directing a user to an item in the user-interface should be
full sentences.
Good: At the top of the Firefox window, click on the Tools menu, and
select Options..."
Bad: Go to Tools > Options...
When creating a troubleshooting document, that presents multiple
solutions, based on the success or failure of a previous suggestion,
[still in discussion].
Instructions for practises which breach net etiquette, should make a
note of it, not make the user feel like a sinful criminal. :-)
_Multimedia_
* _Screenshots_
Don't be shy about including screenshots. Try to include a
screenshot(s) that will help clear any potential misunderstandings of
the article text.
* Screenshots needs to present Firefox in its most familiar form,
which means using as many default settings as possible, including the
default Firefox theme, and default operating system theme.
* Crop what is needed, but make sure the cropped image is still
identifiable. If you need to create an image of the full screen, use a
resolution of 800x600 (just so the image doesn't take a lot of space,
without need).
* When highlighting sections, draw red lines around the section.
Good: <http://images.ilias.ca/tb-searchbar.png>
Bad: <http://images.ilias.ca/tb2-searchbar.png>
* If it doesn't make the image unreadable, decrease the size to 75%
* save for web, in PNG format
* _Videos_
* Videos needs to present Firefox in its most familiar form, which
means using as many default settings as possible, including the default
Firefox theme, and default operating system theme.
Chris Ilias
> When creating a troubleshooting document, that presents multiple
> solutions, based on the success or failure of a previous suggestion,
> [still in discussion].
It looks there's no more feedback on the best practices guide. There are
just a couple of things I want to get cleared up, before declaring it
official. The above is one of them. I don't think we ever came to a
conclusion about what to do about how to present branches of solutions.
Then there's the question of what versions to support. The Firefox 1.5.x
series is dead, and the major update has been pushed; so I don't think
we should bother creating documentation for Firefox 1.5.x.
Majken Connor
working with it. I imagine you'll get a second wave of
questions/suggestions/comments when we're actually editing and
realizing situations where we do/don't like the guide.
Jason Barnabe (np)
> Then there's the question of what versions to support. The Firefox 1.5.x
> series is dead, and the major update has been pushed; so I don't think
> we should bother creating documentation for Firefox 1.5.x.
I don't think we want to regard a document that's missing 1.5 info as
incomplete, but if we get the versions plugin working well there's no
reason we couldn't include info if someone wrote it. This would also
apply to when 2.0 dies and then we're left with all its documentation.
In short, "Write articles that are useful to 2.0 users", not "Don't
write anything about 1.5".
Chris Ilias
> Keep in mind that many of us might not have feedback until we start
> working with it. I imagine you'll get a second wave of
> questions/suggestions/comments when we're actually editing and
> realizing situations where we do/don't like the guide.
Here's the thing: I have to have it done by Friday.
I'll update it with the latest round of feedback; and consider it ready
for use, but still keep it a living document.
Chris Ilias
Could you or Marc, please refresh my memory on what the wiki code will
look like, for text that has content specific to versions of Firefox
*and* operating systems? Are both version and OS going to be specified
in one tag? In other words, if a person wants to switch from Fx2 content
to Fx3 content, will they have to choose OS as well.
Example choices:
- Firefox 2 for Windows
- Firefox 2 for Mac
- Firefox 2 for Linux
- Firefox 3 for Windows
- etc.
I don't think we got an answer with regards to whether or not version
and OS sniffing was possible. I know that we can show/hide specific
content, that can be switched via a menu on the page; but what about
making the default content different, depending on the user's UA?
Chris Ilias
there is a computer literacy barrier that we need to overcome, when
instruction. This means each article should not only provide answers,
default values. In general, try to write articles in such a way, that
your mom would understand.
Write articles that are useful to 2.0 users. Firefox 1.5.x has reach its
end of life; and the major update has been pushed.
It's amazing how some users can misinterpret instructions; so when
describing actions, try to word it in a way that is brief, yet *cannot
be misinterpreted* (words are expensive).
The word "user" itself is a technical term. Try to avoid phrases, like
"If a user has lost his bookmarks." Word your sentences, as if you are
speaking to the user, like "If you've lost your bookmarks..."
The title of the article describes the question being asked or the
problem being enquired about.
Good: Toolbar keeps resetting
Bad: corrupt localstore.rdf
Give a brief (one paragraph max.) summary of the cause of the problem,
and what is being done (in the article) to fix it. This is your
introduction. There's no need to name it as such (or "Background").
Users only need one answer to their question. There are cases in which
there is more than one way of accomplishing a task. In such instances,
try pick the most user-friendly method. In general, the order of
preference is:
1. The graphical user-interface (menus, check-boxes, buttons, etc.)
distributed with Firefox.
2. If it's a preference, that the user is likely only to change once,
use about the about:config method
3. Extension
4. User script (user.js, userChrome.css, userContent.css, etc.)
If none of the above are possible, there's usually one method of
accomplishing a task anyway. :-)
When providing step by step instructions, use a numbered list, rather
than bullets.
Include expected results, when giving instructions (e.g. Choose the
Firefox (Safe mode) menu option. *A dialog will appear.*)
Instructions directing a user to an item in the user-interface should be
full sentences.
Good: At the top of the Firefox window, click on the Tools menu, and
select Options..."
Bad: Go to Tools > Options...
Instructions for practises which breach net etiquette, should make a
note of it, not make the user feel like a sinful criminal. :-)
_Multimedia_
* _Screenshots_
Don't be shy about including screenshots. Try to include a
screenshot(s) that will help clear any potential misunderstandings of
the article text.
* Screenshots needs to present Firefox in its most familiar form,
which means using as many default settings as possible, including the
default Firefox theme, and default operating system theme.
* Crop what is needed, but make sure the cropped image is still
identifiable. If you need to create an image of the full screen, use a
resolution of 800x600 (just so the image doesn't take a lot of space,
without need).
* When highlighting sections, draw red lines around the section.
Good: <http://images.ilias.ca/tb-searchbar.png>
Bad: <http://images.ilias.ca/tb2-searchbar.png>
* If it doesn't make the image unreadable, decrease the size to 75%
* save for web, in PNG format
* _Videos_
* Videos needs to present Firefox in its most familiar form, which
means using as many default settings as possible, including the default
Firefox theme, and default operating system theme.
Jason Barnabe (np)
You can see how in general the markup works at http://doc.tikiwiki.org/PluginVersions
. Plugins are written in PHP and have full access to the headers and
such of a request. We'll of course have to modify that plugin to
default based on the UA, but it shouldn't be hard.
What I'm hoping is that we could categorize the content by both OS and
version when we want to and only one or the other we want to. In other
words, a section marked "Firefox-2" will have content for all OSes
relating to Firefox 2, "Firefox-Windows" will have content for all
versions under Windows, and "Firefox-2-Windows" will have content
specifically for Firefox 2 on Windows. Having all three ways will let
us have fine-grained control when needed and won't make us repeat
content when not needed.
I also imagine there would be text at the top that says something like
"These are instructions for [Firefox 2 on Windows]" with a drop down
of all other possible choices. Right now, the plugin lets you put a
similar navigation element on each piece of content; we'd have to
change that as well (again, doesn't look hard).
Samuel Sidler
No, PNG 24 is what you want. One version of the PNG spec only allowed
256 colors (PNG 8, iirc), the other allows full color. You want the latter.
-ss