Style Guide scratch pad
Chris Ilias
any rules I could think of. Tell me what you think:
TYPES OF PAGES
- reference charts
- how-to pages for basic tasks
- how-to pages for tips/tricks
- troubleshooting
GENERAL
- the target reader is "mom". Don't worry about more advanced users.
- we can have support articles for plug-ins, but what about add-ons? Is
that an AMO thing?
- about:config is always preferred over user.js, unless about:config
won't work.
- if there's an add-on that performs the same function as a user script,
add-ons are generally more user friendly, because they provide a GUI.
- add two spaces after the period at the end of a sentence.
- abbreviations or acronyms should be spelt out, then followed by the
acronym in parenthesis. For example: Secure Sockets Layer (SSL).
- the title of the article describes the question being asked or the
problem being enquired about.
- give a brief (one sentence) summary of the cause of the problem, and
what is being done (in the article) to fix it.
- when describing actions, try to word it in a way that is brief, yet
*cannot be misinterpreted* (words are expensive).
- Plug-ins contains a hyphen (it is not plugins).
- Add-ons contains a hyphen (it is not addons).
- United States English is preferred. (color, not colour).
- when providing step by step instructions, use a numbered list, rather
than bullets.
- references to bug numbers should cited like the MozillaZine KB. Don't
state "bug #####", but use a citation number, like "[1]".
- links to mozilla.com pages should not contain the /en-US/. See:
<http://groups.google.com/group/mozilla.dev.mozilla-org/browse_frm/thread/4b8a28132ddf53d5>.
- instructions for practises which breach net etiquette, should make a
note of it, not make the user feel like a sinful criminal. :-)
LAYOUT
- right now, I'd like to put the edit page and page history links at the
bottom (footer) One way of preventing article feedback from being used a
support forum, is to relabel the link from "Discussion" to something
like "How can we improve this article?"
- have a section within each article that lists what operating systems
to article applies to?
TYPES OF TEXT (aside from regular text):
- Article Title
On most mozilla.com pages, the section underneath the grey banner is
used for the page title, in red text. I don't like that. Let's put it at
the top, beside the menu. More like www.mozilla.org pages. It should be
centered, and in bold text. I don't know about underlining it.
- Section title
Bold, align=left, and underline
- preference names / values
On www.mozilla.org, we use <var> but I don't like it. I think
something like <tt> would be easier to read, and select/copy. We should
possibly designate a colour for prefnames.
- user scripts (user.js, userChrome.css, userContent.css)
No question (IMO): use <code> tags for these
- file names / paths
On www.mozilla.org, we use italics. I'm not sure I like that. There
must be a better presentation.
- keyboard shortcuts
Use <kbd>. I like the style used on www.mozilla.org. I want to keep that.
- menu paths
On www.mozilla.org, we use a grey background, with angle brackets,
separating levels [Tools > Options...]. On my own site, I bold the text,
and use two hyphens and an angle bracket to separate levels
[*Tools-->Options...*]. That's just a result of using newsgroups. I
don't want a line wrap in the middle of a menu path. Right now, I prefer
the www.mozilla.org way; but in the end, I think giving word
instructions is the most user-friendly way [In the menu bar, click on
Tools, and select the item called Options...]. Small note: don't remove
the trailing periods after certain menu items [Options..., Clear Private
Data..., Customize...].
SCREENSHOTS
- unless there's a need to be specific, screenshots should be done on
Windows. (If the contributor doesn't have Windows, that's fine; but if
there's a chance to switch it to a Windows screenshot, take it.)
- crop what's needed. 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, select what you want to highlight,
inversion the selection, and lower the brightness to -80.
Bad: <http://images.ilias.ca/tb-searchbar.png>
Good: <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
- unless there's a need to be specific, videos should be done on Windows.
- if there's no need for a voiceover, don't bother (saves on video file
size)
- flash format is preferred
Jason Barnabe (np)
> I'm working on the style guide for sumo, and I decided to first type out
> any rules I could think of. Tell me what you think:
Here are some additional thoughts I have:
Something that needs to be addressed is branching - how to provide
instructions for multiple versions and how to present "if X happens to
you, do this, otherwise do Y".
Avoid presenting multiple options when one is sufficient.
Write as if you're talking to the user. "If you lost your bookmarks",
not "If a user has lost his bookmarks". Also avoid writing facts
indirectly, like "Some users have reported that..."
Avoid "Note:", "Warning:", and "Caution:". Write complete sentences.
Avoid sections named "Intro" or "Background" - if you're writing an
introduction or background, it should just be at the start of the article.
On to your suggestions:
It might be good to split your suggestions a different way, for example
between content issues and minor nitpicky things.
> - how-to pages for tips/tricks
Is this in the scope of the project?
> - the target reader is "mom". Don't worry about more advanced users.
Need to define "mom" a bit, ex: "Mom" doesn't know how to use
about:config or add a toolbar button without instruction.
Can you spell out what you mean by "don't worry"?
> - we can have support articles for plug-ins, but what about add-ons? Is
> that an AMO thing?
I don't see why we wouldn't provide support articles for add-ons.
> - about:config is always preferred over user.js, unless about:config
> won't work.
Going even further, UI is preferred over about:config.
> - add two spaces after the period at the end of a sentence.
Why? I can think of a bunch of reasons why not.
-The rest of Mozilla (or the web in general) isn't written like this
-You have to do "hack" HTML to even make it show up like that
-It's a carryover from typewriters and monospace fonts.
> - abbreviations or acronyms should be spelt out, then followed by the
> acronym in parenthesis. For example: Secure Sockets Layer (SSL).
Do we really need to tell "mom" what SSL stands for?
> - the title of the article describes the question being asked or the
> problem being enquired about.
I'd rather articles not be phrased as questions. A lot of the KB's
article naming conventions apply.
http://kb.mozillazine.org/Article_naming_conventions
> - give a brief (one sentence) summary of the cause of the problem, and
> what is being done (in the article) to fix it.
Up this to "one paragraph" to give editors a bit more leeway. I don't
want people writing run-on sentences to abide by this. The point is,
keep it brief.
> - references to bug numbers should cited like the MozillaZine KB. Don't
> state "bug #####", but use a citation number, like "[1]".
I actually don't like the way the KB does it. It interrupts the flow of
the article and makes users possibly follow the links, thinking that the
solution is there. Something like Wikipedia has would be better.
> - have a section within each article that lists what operating systems
> to article applies to?
Most articles on the current KB apply to all operating systems. They may
only differ by Tools -> Options vs. Edit -> Preferences.
> TYPES OF TEXT (aside from regular text):
> - Article Title
> On most mozilla.com pages, the section underneath the grey banner is
> used for the page title, in red text. I don't like that. Let's put it at
> the top, beside the menu. More like www.mozilla.org pages. It should be
> centered, and in bold text. I don't know about underlining it.
>
> - Section title
> Bold, align=left, and underline
I'd hope that these things would be out of the hands of the editors and
would just be the layout of the site.
> SCREENSHOTS
We need to figure out how screenshots will be presented in relation to
the text that goes with them.
> - unless there's a need to be specific, screenshots should be done on
> Windows. (If the contributor doesn't have Windows, that's fine; but if
> there's a chance to switch it to a Windows screenshot, take it.)
I don't see the need for this. Firefox on Linux, Mac, and Windows all
look similar enough for the purposes that we would use screenshots.
> - crop what's needed. 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, select what you want to highlight,
> inversion the selection, and lower the brightness to -80.
> Bad: <http://images.ilias.ca/tb-searchbar.png>
> Good: <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
Need to provide editors instructions on how to do these things.
> VIDEOS
> - provide a text version for those without hi-speed
I'd go even further and say that articles should be written assuming
that the video won't work for the user.
> - unless there's a need to be specific, videos should be done on Windows.
Same objection as above.
> - flash format is preferred
We should recommend tools to create videos. Are there any services out
there that convert between popular formats, so we can upload the videos
in any format and view in any format? (Speaking selfishly as a 64-bit
Linux user, I don't want Flash to be the only option)
Kevin Brosnan
> - unless there's a need to be specific, screenshots should be done on
> Windows. (If the contributor doesn't have Windows, that's fine; but if
> there's a chance to switch it to a Windows screenshot, take it.)
> - crop what's needed. 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, select what you want to highlight,
> inversion the selection, and lower the brightness to -80.
> Bad: <http://images.ilias.ca/tb-searchbar.png>
> Good: <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
> - unless there's a need to be specific, videos should be done on Windows.
> - if there's no need for a voiceover, don't bother (saves on video file
> size)
> - flash format is preferred
> support-planning mailing list
> support-...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/support-planning
>
screenshots and videos
- Default theme
- Default toolbar setup
- Default OS theme
- No extensions visible
(unless specifically needed by the article)
Kevin Brosnan
pcab...@gmail.com
wrote:
> We need to figure out how screenshots will be presented in relation to
> the text that goes with them.
>
> > - unless there's a need to be specific, screenshots should be done on
> > Windows. (If the contributor doesn't have Windows, that's fine; but if
> > there's a chance to switch it to a Windows screenshot, take it.)
>
> I don't see the need for this. Firefox on Linux, Mac, and Windows all
> look similar enough for the purposes that we would use screenshots.
I guess the point is to have a articles as homogeneous looking as
possible. Firefox may look similar on Mac OS X, Windows and Linux...
for me. The intended users may think they are different applications
if they have never seen a window in other OS. Windows users are the
majority, even a larger majority if counting non technical users only.
For the same reason I'd suggest the use of the default theme, with the
default UI including toolbars and buttons arrangement. No status bar
icons, extension buttons, toolbars, sidebars, etc. should be on sight.
No chrome tweaks. Unless the tip/article involves themes, chrome
tweaks or the additional UI is added by the subject add-on.
> > - flash format is preferred
>
> We should recommend tools to create videos. Are there any services out
> there that convert between popular formats, so we can upload the videos
> in any format and view in any format? (Speaking selfishly as a 64-bit
> Linux user, I don't want Flash to be the only option)
Theora should be the format of choice specially since Firefox 3 may
include native support for it through the video tag. However I haven't
been able to find an easy to use converter.
David McRitchie
"Kevin Brosnan" <kbro...@gmail.com> wrote in message news:mailman.2498.118287140...@lists.mozilla.org...
> > SCREENSHOTS
> > - unless there's a need to be specific, screenshots should be done on
> > Windows. (If the contributor doesn't have Windows, that's fine; but if
> > there's a chance to switch it to a Windows screenshot, take it.)
> > - crop what's needed. 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, select what you want to highlight,
> > inversion the selection, and lower the brightness to -80.
> > Bad: <http://images.ilias.ca/tb-searchbar.png>
> > Good: <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
> >
> - Default theme
> - Default toolbar setup
> - Default OS theme
> - No extensions visible
> (unless specifically needed by the article)
>
> Kevin Brosnan
I think of the two screen shots the bad one is the best
in fact until I saw the red outline, I had no idea why one
part was white, it certainly does not make for a good
illustration. Skip the color inversions (unrealistic) use
the red outline to point out something.
Probably not much point to showing the entire screen just
to show a search bar. Fitting everything into a screen shot
proportion is one of many things that was done to another
area a bad experience.
And as far as web design goes, I'd sure prefer not to have
background images, or large logos or banners with feathered
edges, and hidden links, more text less graphics. Both look
like they shot through Vaseline rather than being a resolution
thing (some of writing is sharp).
--
David McRitchie,
Firefox Customizations: http://www.mvps.org/dmcritchie/firefox/firefox.htm
Chris Ilias
> Something that needs to be addressed is branching - how to provide
> instructions for multiple versions and how to present "if X happens to
> you, do this, otherwise do Y".
This is a wild idea, but what if such instructions were actually
structured like a tree?
We'll think of something. I just don't have any ideas right now.
> Avoid presenting multiple options when one is sufficient.
I agree.
> Write as if you're talking to the user. "If you lost your bookmarks",
Which reminds me, we need grammar police too. :-)
> not "If a user has lost his bookmarks". Also avoid writing facts
> indirectly, like "Some users have reported that..."
I agree. (about the entire point you were making regarding talking to
the user)
> Avoid "Note:", "Warning:", and "Caution:". Write complete sentences.
I don't know about that. I don't want users to be confronted with a sea
of text.
> Avoid sections named "Intro" or "Background" - if you're writing an
> introduction or background, it should just be at the start of the article.
I agree.
> > - how-to pages for tips/tricks
>
> Is this in the scope of the project?
Eventually. But I was rethinking this last night, and I think would go
something more like:
- reference charts (keyboard shortcuts, toolbar items, menu reference, etc.)
- feature tutorials (how to use tabbed browsing, how to use web feeds, etc.)
- tasks (how to install, how to import data, how to backup data, etc.)
- troubleshooting (lost bookmarks, toolbar keeps resetting, can't
install add-ons, etc.)
>> - the target reader is "mom". Don't worry about more advanced users.
>
> Need to define "mom" a bit, ex: "Mom" doesn't know how to use
> about:config or add a toolbar button without instruction.
Exactly. That means articles should provide instruction. :-)
> Can you spell out what you mean by "don't worry"?
Don't bother creating a more succinct version of an article, for those
who don't have to read through novice instructions. For example, if the
page says:
"Enter about:config in the address bar. In the resulting page, search
for the preference browser.tabs.loadFolderAndReplace.
Double-click on it, which should change the value to false."
Don't create a second version that says:
"Set the pref browser.tabs.loadFolderAndReplace to false."
> Going even further, UI is preferred over about:config.
Definitely agree.
>> - add two spaces after the period at the end of a sentence.
>
> Why? I can think of a bunch of reasons why not.
> -The rest of Mozilla (or the web in general) isn't written like this
> -You have to do "hack" HTML to even make it show up like that
> -It's a carryover from typewriters and monospace fonts.
One space, it is then. :-)
>> - abbreviations or acronyms should be spelt out, then followed by the
>> acronym in parenthesis. For example: Secure Sockets Layer (SSL).
>
> Do we really need to tell "mom" what SSL stands for?
Good point. I guess it depends on the instructions given. (I actually
got that rule from wikipedia.) How about we make sure acronyms use the
<acronym> tag, with title?
>> - the title of the article describes the question being asked or the
>> problem being enquired about.
>
> I'd rather articles not be phrased as questions. A lot of the KB's
> article naming conventions apply.
> http://kb.mozillazine.org/Article_naming_conventions
I probably didn't phrase that correctly. I didn't mean to suggest that
the title='the question', but the title='what the user is thinking'.
Like what was discussed earlier in this group about the difference
between "corrupt localstore.rdf" and "toolbar keeps resetting".
>> - give a brief (one sentence) summary of the cause of the problem, and
>> what is being done (in the article) to fix it.
>
> Up this to "one paragraph" to give editors a bit more leeway. I don't
> want people writing run-on sentences to abide by this. The point is,
> keep it brief.
I agree. I should point out that the style can be ignored in cases, when
needed.
> I actually don't like the way the KB does it. It interrupts the flow of
> the article and makes users possibly follow the links, thinking that the
> solution is there. Something like Wikipedia has would be better.
You mean using <sup> tags? I'm fine with that. Links to bug pages have
always been a bit of a grey area. It's too advanced for most users, but
if cited in a good way, it is an excellent way to let the user know:
- Mozilla knows about the problem
- something is being done about the problem
- you (the user) can track its progress, thus know when it's fixed
As a result, users may get more involved, and be willing to report bugs,
send feedback, or at least wait until the bug is fixed, instead of
switching products.
> Most articles on the current KB apply to all operating systems. They may
> only differ by Tools -> Options vs. Edit -> Preferences.
Okay, no OS section on each page.
The difference in menu paths is something I really hate. It's actually
different on Mac as well (Firefox-->Preferences...). So instead of say
Tools > Options..., it's Tools > Options... (Firefox > Preferences... on
Mac OS X, and Edit > Preferences... on Linux). Not good. I want to avoid
trying to sniff out the readers OS.
>> - Section title
>> Bold, align=left, and underline
>
> I'd hope that these things would be out of the hands of the editors and
> would just be the layout of the site.
That's a good idea. I wonder if templates would fix that.
> We need to figure out how screenshots will be presented in relation to
> the text that goes with them.
I don't think we need captions, if that's what you're getting at. Other
than that, I think this will require different rules for
task/troubleshooting pages and feature tutorials.
>> - unless there's a need to be specific, screenshots should be done on
>> Windows. (If the contributor doesn't have Windows, that's fine; but if
>> there's a chance to switch it to a Windows screenshot, take it.)
>
> I don't see the need for this. Firefox on Linux, Mac, and Windows all
> look similar enough for the purposes that we would use screenshots.
What pcab...@gmail.com said. :-)
> > - crop what's needed. 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, select what you want to highlight,
> > inversion the selection, and lower the brightness to -80.
> > Bad: <http://images.ilias.ca/tb-searchbar.png>
> > Good: <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
>
> Need to provide editors instructions on how to do these things.
I agree. I'm also a little worried about the availability of tools to
accomplish the above.
>> - flash format is preferred
>
> We should recommend tools to create videos. Are there any services out
> there that convert between popular formats, so we can upload the videos
> in any format and view in any format? (Speaking selfishly as a 64-bit
> Linux user, I don't want Flash to be the only option)
I don't know.
Chris Ilias
> screenshots and videos
> - Default theme
> - Default toolbar setup
> - Default OS theme
> - No extensions visible
> (unless specifically needed by the article)
I think we can simplify this to "When creating screenshots or videos, do
it in a new profile."
Jason Barnabe (np)
>> Can you spell out what you mean by "don't worry"?
>
> Don't bother creating a more succinct version of an article, for those
> who don't have to read through novice instructions. For example, if the
> page says:
> "Enter about:config in the address bar. In the resulting page, search
> for the preference browser.tabs.loadFolderAndReplace.
> Double-click on it, which should change the value to false."
>
> Don't create a second version that says:
> "Set the pref browser.tabs.loadFolderAndReplace to false."
Yeah, that's fine with me. What I'm trying to do on mozillaZine is say
what the user is to do, then provide step by step instructions on how to
do it. So for example:
"You can solve your problem by setting name.of.pref to 1:
# Type about:config in the Location Bar..."
That way novice users get their instructions, and advanced users don't
have to wade though instructions on stuff they already do.
In general, we're writing for novice users, but we can keep advanced
users in mind if it doesn't hurt the novice ones.
>>> - abbreviations or acronyms should be spelt out, then followed by the
>>> acronym in parenthesis. For example: Secure Sockets Layer (SSL).
>>
>> Do we really need to tell "mom" what SSL stands for?
>
> Good point. I guess it depends on the instructions given. (I actually
> got that rule from wikipedia.) How about we make sure acronyms use the
> <acronym> tag, with title?
Wikipedia's about giving definitions, so it makes sense there. I would
prefer the acronym/title thing.
> You mean using <sup> tags? I'm fine with that. Links to bug pages have
> always been a bit of a grey area. It's too advanced for most users, but
> if cited in a good way, it is an excellent way to let the user know:
> - Mozilla knows about the problem
> - something is being done about the problem
> - you (the user) can track its progress, thus know when it's fixed
>
> As a result, users may get more involved, and be willing to report bugs,
> send feedback, or at least wait until the bug is fixed, instead of
> switching products.
I was actually thinking more from an editor's perspective. When you
write something, write where you got the info from so future editors
know when the problem's fixed (if it's a bug report) and that you didn't
just make stuff up.
> The difference in menu paths is something I really hate. It's actually
> different on Mac as well (Firefox-->Preferences...). So instead of say
> Tools > Options..., it's Tools > Options... (Firefox > Preferences... on
> Mac OS X, and Edit > Preferences... on Linux). Not good. I want to avoid
> trying to sniff out the readers OS.
I'd actually like to sniff the reader's OS and present them with only
the information that applies to them. By "sniff" I mean automatically
reading the user agent or something.
>> We need to figure out how screenshots will be presented in relation to
>> the text that goes with them.
>
> I don't think we need captions, if that's what you're getting at. Other
> than that, I think this will require different rules for
> task/troubleshooting pages and feature tutorials.
No, I don't mean captions. I mean that images naturally go with certain
text. If I say "Open Safe Mode, and a dialog will come up", a screenshot
would be related to that text. Would it appear left, right, above,
below...
Jason Barnabe (np)
> On Jun 26, 1:03 am, "Jason Barnabe (np)" <jason_barn...@fastmail.fm>
> wrote:
>> We need to figure out how screenshots will be presented in relation to
>> the text that goes with them.
>>
>>> - unless there's a need to be specific, screenshots should be done on
>>> Windows. (If the contributor doesn't have Windows, that's fine; but if
>>> there's a chance to switch it to a Windows screenshot, take it.)
>> I don't see the need for this. Firefox on Linux, Mac, and Windows all
>> look similar enough for the purposes that we would use screenshots.
>
> I guess the point is to have a articles as homogeneous looking as
> possible. Firefox may look similar on Mac OS X, Windows and Linux...
> for me. The intended users may think they are different applications
> if they have never seen a window in other OS. Windows users are the
> majority, even a larger majority if counting non technical users only.
I understand that it would be a win for the users, but I'm concerned
that it would essentially discourage non-Windows users from posting
screenshots and videos. I don't think that it's worth it.
Jason Barnabe (np)
> I think of the two screen shots the bad one is the best
> in fact until I saw the red outline, I had no idea why one
> part was white, it certainly does not make for a good
> illustration. Skip the color inversions (unrealistic) use
> the red outline to point out something.
>
> Probably not much point to showing the entire screen just
> to show a search bar. Fitting everything into a screen shot
> proportion is one of many things that was done to another
> area a bad experience.
I agree. It's not the best example to compare the two because you would
likely have a smaller window or crop the thing down anyway.
Are there situations where we would want to point out two things in one
screenshot? How would that be accomplished with the fade effect?
pcab...@gmail.com
wrote:
Chris suggestion is not making Windows a requirement but a
recommendation so hopefully people won't be discouraged by it.
Chris Ilias
> I'm working on the style guide for sumo, and I decided to first type out
> any rules I could think of. Tell me what you think:
More quick thoughts:
- it's themes, not skins
- it's web feeds, not RSS feeds (although, we should mention RSS,
because a lot of websites still use the term RSS)
- it's a lot, not alot. :)
- is it web sites, or websites?
- is it homepage, or home page?
- it's search engines, not search plug-ins
- in cases like "you have" and "do not", use the shortened versions:
"you've" "don't"
- period before or after quotation marks?
Chris Ilias
In <http://ilias.ca/blog/2007/02/turn-off-tab-scrolling-in-firefox-2/>,
I used Photoshop.
I just tested MS Paint and IrfanView, and neither of them seem to be
able to have two selected areas at the same time.
I prefer the brightness adjustment method, because I don't want users
mistaking red lines as part of the UI, and I just think it looks more
professional.
But if the consensus is that drawing lines on the sreenshot is
preferred, I'm fine with that. :-)
Majken Connor
> >> acronym in parenthesis. For example: Secure Sockets Layer (SSL).
> >
>
> Good point. I guess it depends on the instructions given. (I actually
> got that rule from wikipedia.) How about we make sure acronyms use the
> <acronym> tag, with title?
I agree, users don't need to know what the acronym stands for. We
might want to think about ways to make this stuff easier to look up,
or maybe we don't want to worry about it since people have search
bars. A glossary of terms would fit under tips and tricks though, so
maybe later on.
>
> >> - the title of the article describes the question being asked or the
> >> problem being enquired about.
> >
> > I'd rather articles not be phrased as questions. A lot of the KB's
> > article naming conventions apply.
> > http://kb.mozillazine.org/Article_naming_conventions
>
> I probably didn't phrase that correctly. I didn't mean to suggest that
> the title='the question', but the title='what the user is thinking'.
> Like what was discussed earlier in this group about the difference
> between "corrupt localstore.rdf" and "toolbar keeps resetting".
This is where tagging and redirects come into play. Some things don't
have a clear winner over what phrase users are going to use to find
it. As well people who are already familiar with the issue and are
looking up the article again are sometimes going to have an easier
time finding the article based on issue than symptom. Not saying we
should organize based on that, but to make sure we make use of
redirects and tags to make sure people can get to the articles easily.
-Majken
pcab...@yahoo.com
> - is it web sites, or websites?
> - is it homepage, or home page?
I think any of those are understandable, but to keep it consistent
with Firefox UI it should be home page, web site, web feeds, web page
and so on.
> - period before or after quotation marks?
I am not a native English speaker but it seems US English prefers it
inside quotations while UK English does outside (http://
en.wikipedia.org/wiki/Quotation_marks). Since it has already been
suggested to go with US English (color preferred to colour), keeping
periods inside seems like the way to go.
pcab...@yahoo.com
+ Default OS theme. For Windows at least it should be explicitly
stated it means Luna blue on Windows XP (not Silver or Olive). On
Vista, could the title bar transparency make a significant enough
difference to need to specify a certain desktop wallpaper?
Chris Ilias
> + Default OS theme. For Windows at least it should be explicitly
> stated it means Luna blue on Windows XP (not Silver or Olive). On
> Vista, could the title bar transparency make a significant enough
> difference to need to specify a certain desktop wallpaper?
It occurs to me, we should probably prefer Vista rather than XP.
pcab...@gmail.com
> It occurs to me, we should probably prefer Vista rather than XP.
It may be a matter of timing. Since the reason for suggesting Windows
is, I understand, because of being the OS for the largest user share,
we can extend the reasoning to XP since it's the most used version
currently and at least until the time Firefox/Thunderbird 3 are
released. Considering a visual refresh is scheduled for FF3 at least
it will be necessary a screenshot update anyways (which can be matter
of another discussion) and then Vista could be the preferred OS.
Chris Ilias
> - right now, I'd like to put the edit page and page history links at the
> bottom (footer) One way of preventing article feedback from being used a
> support forum, is to relabel the link from "Discussion" to something
> like "How can we improve this article?"
> - have a section within each article that lists what operating systems
> to article applies to?
It might also be a good idea to have a link to the support forum at the
end of each article. For example: "If you're still having trouble, you
can post a question in the <a>support forum</a>." (The wording would be
different on how-to articles.)
Chris Ilias
> state "bug #####", but use a citation number, like "[1]".
>
> - Section title
> Bold, align=left, and underline
>
> - preference names / values
> On www.mozilla.org, we use <var> but I don't like it. I think
> something like <tt> would be easier to read, and select/copy. We should
> possibly designate a colour for prefnames.
>
> - user scripts (user.js, userChrome.css, userContent.css)
> No question (IMO): use <code> tags for these
>
> - file names / paths
> On www.mozilla.org, we use italics. I'm not sure I like that. There
> must be a better presentation.
>
> - keyboard shortcuts
> Use <kbd>. I like the style used on www.mozilla.org. I want to keep that.
>
> - menu paths
> On www.mozilla.org, we use a grey background, with angle brackets,
> separating levels [Tools > Options...]. On my own site, I bold the text,
> and use two hyphens and an angle bracket to separate levels
> [*Tools-->Options...*]. That's just a result of using newsgroups. I
> don't want a line wrap in the middle of a menu path. Right now, I prefer
> the www.mozilla.org way; but in the end, I think giving word
> instructions is the most user-friendly way [In the menu bar, click on
> Tools, and select the item called Options...]. Small note: don't remove
> the trailing periods after certain menu items [Options..., Clear Private
> Data..., Customize...].
Now that Tikiwiki is chosen, we'll need to adapt these.
Chris Ilias
>> - preference names / values
>> On www.mozilla.org, we use <var> but I don't like it. I think
>> something like <tt> would be easier to read, and select/copy. We
>> should possibly designate a colour for prefnames.
Designating a colour is looking to be pretty hard. I can click on the
"colored text" icon, I cannot chose a colour, before the code is
actually applied; which means, I have to edit it by hand.
>> - user scripts (user.js, userChrome.css, userContent.css)
>> No question (IMO): use <code> tags for these
Perhaps monospace font will do, for this, using -+test+-.
In general it works, but unlike code tags, it doesn't honour line
breaks; which means we'd have to put the same tags at the start and end
of each line:
-+#bookmarks-ptf {display:block !important;}+-
-+#bookmarks-ptf toolbarseparator {display:inline !important;}+-
>> - file names / paths
>> On www.mozilla.org, we use italics. I'm not sure I like that. There
>> must be a better presentation.
Italics = two *single* quotation marks.
''userChrome.css''
>> - keyboard shortcuts
>> Use <kbd>. I like the style used on www.mozilla.org. I want to keep
>> that.
This one, I have no clue.
>> - menu paths
>> On www.mozilla.org, we use a grey background, with angle brackets,
>> separating levels [Tools > Options...]. On my own site, I bold the
>> text, and use two hyphens and an angle bracket to separate levels
>> [*Tools-->Options...*]. That's just a result of using newsgroups. I
>> don't want a line wrap in the middle of a menu path. Right now, I
>> prefer the www.mozilla.org way; but in the end, I think giving word
>> instructions is the most user-friendly way [In the menu bar, click on
>> Tools, and select the item called Options...]. Small note: don't
>> remove the trailing periods after certain menu items [Options...,
>> Clear Private Data..., Customize...].
I can't seem to find a way to assign background colour to text.
Ultimately, I'd love it if we could have span classes for each of the
above. So instead of worrying about which tags to use, we can enclose a
pref in <span class="pref">pref.name</span>, and so on. That way, if we
do make any changes to the how these types of text are displayed, we
don't have to go through each article.
I'd also love it, if we can increase the font size of text, displayed in
the editor.
Chris Ilias
> No, I don't mean captions. I mean that images naturally go with certain
> text. If I say "Open Safe Mode, and a dialog will come up", a screenshot
> would be related to that text. Would it appear left, right, above,
> below...
I think this should be left open, for each article; because it depends
on the size and dimensions of the screenshot, as well as the purpose of
the screenshot.
Marc Laporte
>
> I can't seem to find a way to assign background colour to text.
> Ultimately, I'd love it if we could have span classes for each of the
> above. So instead of worrying about which tags to use, we can enclose a
> pref in <span class="pref">pref.name</span>, and so on. That way, if we
> do make any changes to the how these types of text are displayed, we
> don't have to go through each article.
>
I agree. Same thing for image layout.
We should use existing wiki syntax when it's logical/relevant. And
create/adapt some plugins as necessary.
I copied and reformatted
http://www.mozilla.org/support/firefox/profile
to:
http://steelgryphon.com/tikicvs/tiki-index.php?page=Firefox+profiles
as an example.
And you can see many examples (menu paths, keyboard shortcuts, etc)
(Refresh your CSS cache if you don't see)
What would be some good examples of standard pages which would have
examples of all the cases?
> I'd also love it, if we can increase the font size of text, displayed in
> the editor.
Done
M ;-)
Jason Barnabe (np)
> Chris Ilias wrote:
>
> > I can't seem to find a way to assign background colour to text.
> > Ultimately, I'd love it if we could have span classes for each of the
> > above. So instead of worrying about which tags to use, we can enclose a
> > pref in <span class="pref">pref.name</span>, and so on. That way, if we
> > do make any changes to the how these types of text are displayed, we
> > don't have to go through each article.
>
> I agree. Same thing for image layout.
>
> We should use existing wiki syntax when it's logical/relevant. And
> create/adapt some plugins as necessary.
>
> to:http://steelgryphon.com/tikicvs/tiki-index.php?page=Firefox+profiles
> as an example.
>
> And you can see many examples (menu paths, keyboard shortcuts, etc)
> (Refresh your CSS cache if you don't see)
>
> What would be some good examples of standard pages which would have
> examples of all the cases?
>
> > I'd also love it, if we can increase the font size of text, displayed in
> > the editor.
>
> Done
>
> M ;-)
Is it easy to add quicktags that will add the markup? Is it also easy
to extend the syntax so that instead of putting in
{DIV(class=mnu,type=>span)}File > Exit{DIV}
we could put in
{MENU}File > Exit{MENU}
and have it converted into the proper HTML?
Marc Laporte
Jason Barnabe (np) wrote:
>
> Is it easy to add quicktags that will add the markup?
Yes. When editing a page, if you have admin rights, click "admin
quicktags". We'll need some nice icons.
Is it also easy
> to extend the syntax so that instead of putting in
>
> {DIV(class=mnu,type=>span)}File > Exit{DIV}
>
> we could put in
>
> {MENU}File > Exit{MENU}
>
> and have it converted into the proper HTML?
>
Yes, but it would be:
{MENU()}File > Exit{MENU}
And the html would be converted to whatever we want. And controlled by
editing one file. For the record, it would be here:
lib/wiki-plugins/wikiplugin_menu.php
M ;-)
Chris Ilias
> On 6/26/07 1:03 AM, _Jason Barnabe (np)_ spoke thusly:
>> Something that needs to be addressed is branching - how to provide
>> instructions for multiple versions and how to present "if X happens to
>> you, do this, otherwise do Y".
>
> This is a wild idea, but what if such instructions were actually
> structured like a tree?
>
> We'll think of something. I just don't have any ideas right now.
How about we use sub-lists for this?
* content1
** if content1 did work
** if content1 did not work, try content1.2
*** if content1.2 did work
*** if content1.2 did not work
* content2
** if content2 did work
** if content2 did not work
Majken Connor
the thing that got the most confused and misunderstood. I think
people handled bookmarks to further down the page. I think the big
problem with it is information overload, people have to wade through
the suggestions for what applies to them and what doesn't and some
people get really confused in what they should do.
It's hard to picture the flow without a good example though. There
are going to be lots of different cases that are more or less complex
and I think the answer will be different for each. If it's a simple
"if this is your symptom you do one thing, if the other thing is your
symptom do the other" I think people handle it better given anchors to
go to the section that applies to them. "If this is what happens,
read this section"
In some cases maybe this is the a good place for the collapsable
text? Leave the general everything's going right instructions, but if
there are some cases where people have problems have "If you hit this
bump, click here" and that expands what they need to do to be able to
continue on to the next step?