Talk:In-house style

From MozillaZine Knowledge Base
Jump to navigationJump to search

Archive of resolved issues

Some of the issues discussed here seem to have been resolved for all intents and purposes, so I'm moving them to Talk:In-House Style/Resolved to clear away the clutter. --Wintogreen 00:35, 27 Mar 2005 (PST) In particular:

  • Rules; article titles
  • Articles that apply to two or more products
  • Capitalization of common terms

If you want to re-open one of these discussions, please do it here on this page, not on the archive page.

Application names

How do we refer to the browser included within the Mozilla Suite? Is it itself called Mozilla Suite, or do we refer to it as the "Mozilla Suite browser" or the "browser in the Mozilla Suite" or something else? Surely many articles for the Mozilla Suite pertain solely to the browser component and not to the whole suite. --Mozcerize 05:54, 10 Apr 2005 (PDT)

I thought we'd just call it Mozilla Suite, when it's clear info only applies to the browser.--asqueella
But sometimes it's not clear: see increasing startup speed where It is not obvious which app we are talking about if we don't specify that it's the browser. --Mozcerize

I think we talked about this before, briefly, but are we sure we're going to stick with "Mozilla Suite" now that the "SeaMonkey" project has an official name? Already I see "Seamonkey" being used in one new page (Standard diagnostic). If we decide to go with SeaMonkey, it's going to be a major pain to change everything. Again. --Wintogreen 05:51, 6 Jul 2005 (PDT)

I removed "Seamonkey" from the article to avoid confusion, now that SeaMonkey 1.0 has been released and we are referring to it on the kb. This way, there is no mention in this article of applications other than the official Mozilla products. Alice Wyman 13:32, 14 March 2006 (UTC)

-> vs. |

I’m just hoping to initiate some discussion as to the relative merits of “->” and “|” for denoting menu sequences:

"Tools -> Options -> Privacy -> Cookies"

"Tools | Options | Privacy | Cookies"

I’ve seen both used all over the place. Also, there seems to be little concensus on what to do about tabs (eg Privacy in the the example above is the equivalent of a tab in an options dialog) and subsections (eg Cookies in the example above). Are these to be treated in the same way (ie using -> or |)? It would be useful to turn to some of the computing textbooks out there and copy what they do. Does anyone have any comments on this? --Mozcerize

Whichever one is chosen should apply to both tabs and menus, I suppose, for consistency matters; you could add a "(tab)" parenthetical remark next to the tab to clarify matters (e.g. "Menu -> Menu -> Dialog -> General (tab)"). --hao2lian
What about the HTML entity → (→)? For what it's worth, I've seen textbooks that use the pipe but never the discrete characters dash and greater-than. --Unarmed 07:02, 23 Feb 2005 (PST)
Well, → is certainly a lot nicer than ->, but the trouble is that it’s always difficult to get people to use HTML entities, particularly when the symbol is going to be typeset frequently. The advantage of “|” is that it’s very easy to type! --Mozcerize
I vote for using "->" and if possible, install a Mediawiki hack that will replace that with a pretty arrow. We should also note on this page whether it is recommended to put spaces before and after the arrow. --asqueella
Well, if tha Mediawiki hack is possible then I vote for that too. It seems like the best compromise. --Mozcerize
The appearance of -> varies. Depending on the height of the hypen, it may not look much like an arrow. I recommend > . It implies a sense of direction (as '|' does not), it's easy to type, and it doesn't depend much on fonts. --AnotherGuest.

Hyphen vs. dash

PS, I totally agree with differentiating hyphens and dashes. (A pet peeve for me, too!) Now if only I can convince everyone to use single and double quotation marks (‘ [‘], ’ [’], “ [“], ” [”]) instead of single and double neutral quotes (', " achieved using your ASCII keyboard) in every situation except marking up computer code…. Even better, will I manage to get people to use a single right quotation mark (’ [’]) instead of a single neutral quote (') or the equivalent (and hence completely misnamed) entity ' when typing an apostrophe? :-P

kerz could be petitioned to install a Mediawiki hack to do this, since I'm sure there's one out there. --hao2lian

OK, so these characters don’t look too “curly” in the default font and size on Firefox, but they certainly do when you increase the text size in a couple of times—try it! Also, the difference is very obvious in smaller font sizes in serif fonts, and in the default font and size in IE. All of these suggestions are advocated by Unicode [1] (View the PDF for Chapter 6, Section 6.2, General Punctuation.) Note that the use of the entity name ‘apos’ was a horrendous blunder made in the days before decent computer fonts were mainstream. --Mozcerize 04:01, 10 Feb 2005 (PST)


Whitespace around dashes

Personally I prefer using whitespace around emdashes, especially since Gecko still doesn't properly allow linebreaks after that character.

Personally, I prefer a tiny bit of whitespace around emdashes too. However, the amount varies from publisher to publisher, and it is correctly achieved not by surrounding the emdash with inter-word spaces but simply by typesetting the emdash with some surrounding space "built in" to the character. So it's really a Gecko issue rather than a user issue. I wasn't aware that Gecko refuses to break lines after emdashes. The spacing issue is an irritant but not a bug; the line-break issue is a bug. I shall go and investigate it! --Mozcerize 01:06, 22 Feb 2005 (PST)
I believe the issue is covered by either Bug 95067: line-break should be allowed after hyphens (unless followed by a number) or Bug 255990: Characters below U+0100 are not subject to line breaking rules at all --Unarmed 20:39, 26 Feb 2005 (PST)


Active voice

Unarmed, I think you mean "use the imperative" rather than "use the active voice". "Help old ladies", "helping old ladies" and "helped old ladies" are all in the active voice. --Mozcerize 03:17, 23 Feb 2005 (PST)

Yes. I knew what I meant, but I had the incorrect term -- I just knew that it wasn't "infinitive." :) --Unarmed 06:53, 23 Feb 2005 (PST)
Ok, changed. :) --Mozcerize

Is it really a good idea? To my eye, Uninstalling extensions is better than Uninstall extensions and Using keyword searches is better than Use keyword searches. The former implies there's a walk-through or a tutorial on the topic, the latter looks like you advise user to uninstall all of his extensions. --asqueella

Well, I largely agree with you asqueella. In general these things look better when the present participle is used, as in "uninstalling extensions". (The original proposal to use the imperative form was not mine. I believe Wikipedia advocate the use of the present participle too.) I would say that all in-page headings should be in this format.
For topic titles, one advantage of using the imperative is when it comes to linking one page to another. In many articles in the KB, you want to be able to say things like "If you are having trouble finding what you want, you should use keyword searches" and you would be able to provide the link to "use keyword searches" simply by typing [ [use keyword searches] ]. However, you gain nothing when the first letter of the topic title is capitalized, since you would normally have to reword the link to remove the capitalization anyway.
Hence, I advocate either abandoning initial capitalization and using the imperative, or keeping initial capitalization and using the present participle.
--Mozcerize 02:16, 26 Feb 2005 (PST)
"For topic titles, one advantage of using the imperative is when it comes to linking one page to another."
But then you can't use accidental linking when using the participle, e.g. "Uninstalling extensions is very easy" :)
I think that we should use present participle when appropriate and decapitalize first letters of words. --asqueella
"But then you can't use accidental linking when using the participle, e.g. "Uninstalling extensions is very easy" :)"
lol, indeed :-)
I agree with your suggestion. --Mozcerize

Hmm. I say it depends on the article. To my ear, "Using Templates" sounds better than "Use Templates" but "Resend Message" sounds better than "Resending Message". So, let the page authors use their own judgment. And by the way, "infinitive" is the correct term; it's just that imperatives use the infinitive form. --wintogreen

Well, "Resend Message" sounds like it's a phrase taken from a dialog or button or something, so it should be kept unchanged. I think that outside of that context, "resending a message" sounds better that "Resend message". At the moment the KB is a mix of both, even on the same page, which is far from ideal.
BTW, "imperative" is the correct term. An infinitive in English consists (usually) of the word "to" followed by a verb form (sometimes called a bare infinitive). The imperative is simply the bare infinitive (ie the infinitive with "to" removed).
--Mozcerize 08:31, 27 Feb 2005 (PST)

Update: I went ahead and deleted the line about using the imperative, due to the lack of consensus here. Unless we can come up with an easily agreed upon, simply expressed guideline, I don't think there's any point in including it in the Style guide. --Wintogreen 01:08, 27 Mar 2005 (PST)

Keyboard shortcuts

Should keyboard shortcuts like Ctrl+D be in quotes or italicized or bold? --asqueella

Ideally, someone should allow the kbd HTML element and we can worry about it in CSS. And while the subject is up, I propose we enclose modifier keys and function keys in brackets: [Ctrl]+D, [F7], [Shift]+[Del] --Unarmed 17:01, 26 Feb 2005 (PST)
fwiw, I'm not fond of enclosing keys in square brackets. And it's not widely used currently. Not sure that element is a good idea - just think about all the times you'll have to type: ... --asqueella 17:14, 26 Feb 2005 (PST)
I could concede the brackets, but I really do feel that kbd is the most appropriate option here. It's also used in the internal Firefox help file. --Unarmed 20:22, 26 Feb 2005 (PST)
I think kbd is appropriate, but it's going to be quite hard to enforce. Many people really don't like typing much ;-). Is there any way of using an easier ASCII structure (eg ^) to indicate keyboard input, and then get the Wiki to do its funky stuff to convert it? --Mozcerize
I vote for quotes, as currently in the current In-House Style page. It's easy to type, easy enough to read, and consistent with using quotes for menu hierarchy. Italics and bold should be used for emphasis, not for describing mouse movements or keystrokes. IMHO, of course. I would change my vote to if a formatting button could be added for it; it'd be too tedious to have to type it out all the time. --wintogreen

URLs

Please don't use the syntax [[wikipedia:articlename]] to link to an article on Wikipedia, since this prevents the link from being recognized as external to the KB and hence it is not displayed with the " " symbol. This is confusing for users, since ordinarily only internal links are displayed without this symbol. (The syntax exists to make Wikipedia authors' lives easier, and is available in the KB purely because this Wiki is based on the one they use.) Instead, link to Wikipedia using [http://en.wikipedia.org/wiki/articlename].

This could be changed by removing (or changing) the #bodyContent a.extiw, #bodyContent a.extiw:active rule from line 538 of /stylesheets/monobook/main.css. --Unarmed 13:37, 8 Mar 2005 (PST)
Indeed, I've requested that some such change be made to the stylesheet. --Mozcerize 01:52, 9 Mar 2005 (PST)

Terminology and hyphenation

plugin or plug-in

I like plugin more, and I also think it's more correct (talking about noun). Anyone has opinions on this?

hao2lian has gone ahead and replaced plug-in -> plugin on the page I was thinking about (Windows Media Player). Adding this variant to the main page, if you think this is incorrect, comment here.

asqueella

popup or pop-up

I think the same argument applies here as it did in the "plugin vs. plug-in" case; popup is the noun synonymous with "pop-up window", and pop-up is an adjective used to describe (amongst other things) pop-up windows. Thoughts? (See also Talk:Popups not blocked#pop-ups or popups?.) Note that Firefox's dialogs and Help use "popup" exclusively, and so I support this usage in the KB too, otherwise we end up with articles talking about "pop-ups" yet containing instructions to choose the option "block popups" in the Options dialog, which just looks ugly. --Mozcerize 09:26, 14 June 2006 (UTC)

Popup vs. pop-up also came up here: Talk:Making pop-ups always resizable. From what I've gathered, popup is correct when used as a noun, so I would go with it, since it was mentioned in the earlier pop-ups or popups discussion that the KB ... won't search for "pop" and hence misses all pages containing "pop-up". The phrase "pop-up" is correct when used as an adjective OR as a noun and both "popup" and "pop-up" are given as synonyms for pop-up advertisement (en.wiktionary.org) . Personally, I would go with "popup" when used as an adjective also, even though "pop-up" may be technically correct, just to make things uniform and to facilitate kb searches Alice Wyman 00:07, 15 June 2006 (UTC)
I too would prefer to use popup in all cases. We'll leave this open to comments for a while, and then I'll add it to In-house Style. --Mozcerize 13:49, 15 June 2006 (UTC)

Web page or webpage

A discussion about using "web page" versus "web page" came up on another Talk page. I moved it here. Alice Wyman 10:44, 20 July 2006 (UTC)

Just a couple of things: is it going to be "web page" or "webpage" (or even "Web page" or "Webpage")? What do other articles use, and do we have an in-house style recommendation for this? (If not, we should create one.) --Mozcerize 08:42, 23 June 2006 (UTC)

I used "webpage" when it's an adjective ("webpage authors", "webpage scripts") and "web page" as a noun, same as it's done on Background music doesn't play although I'm not sure if that's correct or even if it's consistent across different pages I've edited! Wikipedia redirects "webpage" to Web page and, except for the opening sentence, A web page or webpage is a resource it uses "Web pages" everywhere else. I checked wiktionary.org for webpage and "web page" is the preferred spelling, "webpage" is the alternate. I couldn't find a definition for "webpage" as an adjective. Anyway, whatever you decide I can live with. I'd prefer "web page" in the text of the article but I think I'll use "website" in the title for now, since that's what most articles do, even when they mean web pages. Alice Wyman 11:54, 23 June 2006 (UTC)
I like your suggested use of "webpage" and "web page" for the adjective and noun respectively. --Mozcerize 08:03, 24 June 2006 (UTC)
It made sense to me at the time (if only because a compound-word adjective seems awkward without hyphenating it!), but later I thought you might want a single usage of either "web page" or "webpage" for both noun and adjective, to simplify matters. On second thought, I think "webpage" might be the better choice if you want a single term since it works better (to me) as an adjective, and would be similar to how "websites" is used in so many articles ..... "webpage" vs "website" is another whole issue... See http://en.wikipedia.org/wiki/Website and http://en.wiktionary.org/wiki/Website
Maybe this topic should be moved to another discussion (maybe to Talk:In-house style) since it is such a commonly-used term. Alice Wyman 08:46, 24 June 2006 (UTC)

moved pages with Kb: prefix back

They don't make sense. Either use a namespace or don't prefix them at all. The person who made those changes hasn't contributed recently (and only made those changes). asqueella 03:29, 29 Mar 2005 (PST)

Special formatting

Path, folder and file names

I think it was decided to use <tt> tags for these, but does that mean quote marks around the folder/file name should no longer be used (as was the original suggestion)? Here's a test case where I used <tt> for folder names without quotes. Doesn't look great to me. Ideas? --wintogreen

Hm, I must have missed something, but I don't remember the suggestion to use quotes around file names and paths. I remember that suggestion for keyboard shortcuts only.
About file paths, I brought this up, suggesting the use of <tt>, Unarmed replied saying his only requirement is using fixed-width, and nobody else commented for quite a while. To my eye, <tt> looks okay. Not perfect, but okay. Do you like quotes + variable width, like "profile"? asqueella
I wouldn't like to see quotes + variable width; we're already using that for several different things. I too think that fixed width is important. I also agree that it doesn't look perfect, but it's okay.
Can't remember if I've said this before, but I think folders whose location varies should be written as <profile folder> and <install folder> so that subfolders would be written as <profile folder>/chrome etc. If the author wishes he can link to the Profile folder article, eg < profile folder>/chrome. --Mozcerize 15:02, 29 Mar 2005 (PST)
Thanks for the feedback. Asquella, the original idea was to use quote marks around just file names (not folder names also; my mistake). You'll see it if you go back in the page history. Quote marks with <tt> actually looks OK, but I think it's formatting overkill. (I'm going to resume my comments below. No indent...) --wintogreen
Just a quick note, I thought Mozcerize meant to use "<profile folder>" when it's part of a path only. I.e. "Find your profile folder", but "<profile folder>/chrome/chrome.rdf", so example (3) doesn't make sense.
So I think actually what you mean is to enclose paths, e.g. C:\Program Files\Mozilla Firefox or <profile folder>\extensions in <tt> tags, but name of files/directories, like "chrome" or "cookies.txt" in parentheses. That's fine with me. <tt> inside quotes looks bad to me. --asqueella
Yes, that's what I intended; (3) is not what I meant. --Mozcerize

I fully agree that <tt> works best in some situations, such as Overlays and Profile Manager (where you can see someone has used <tt> for the Windows section), and I can see why <profile folder> would be better for some situations. But I think there are a number of articles where this formatting doesn't work so well. Sometimes it's a little ugly and distracting, and simple quote marks do work better to communicate the idea of "a file/folder named X". See mockups below. I'd prefer a little flexibility in this style guideline, depending on the context in which the folder/file names appear. --Wintogreen 23:03, 29 Mar 2005 (PST)

(1) Currently existing text, "as is", from Profile backup

  1. Completely close all Mozilla programs, including the Mozilla Suite, Firefox, and Thunderbird. Don't forget to exit the Mozilla Suite's Quick Launch if it's open (as indicated in the Windows system tray).
  2. Find your profile folder. Go up in the folder hierarchy until you see the folder that contains the folder "Profiles" and the files "pluginreg.dat", "registry.dat", and "profiles.ini" (not all files may exist). Go up once again and copy this entire folder. For the Mozilla Suite, Firefox, or Thunderbird, this folder's name should be "Mozilla", "Firefox", or "Thunderbird", respectively.
  3. Copy (but not move) your entire profile folder to another location.

(2) Using <tt> without quote marks

  1. Completely close all Mozilla programs, including the Mozilla Suite, Firefox, and Thunderbird. Don't forget to exit the Mozilla Suite's Quick Launch if it's open (as indicated in the Windows system tray).
  2. Find your profile folder. Go up in the folder hierarchy until you see the folder that contains the folder Profiles and the files pluginreg.dat, registry.dat, and profiles.ini (not all files may exist). Go up once again and copy this entire folder. For the Mozilla Suite, Firefox, or Thunderbird, this folder's name should be Mozilla, Firefox, or Thunderbird, respectively.
  3. Copy (but not move) your entire profile folder to another location.

(3) Using <tt> plus <profile folder>without quote marks

  1. Completely close all Mozilla programs, including the Mozilla Suite, Firefox, and Thunderbird. Don't forget to exit the Mozilla Suite's Quick Launch if it's open (as indicated in the Windows system tray).
  2. Find your <profile folder>. Go up in the folder hierarchy until you see the folder that contains the folder Profiles and the files pluginreg.dat, registry.dat, and profiles.ini (not all files may exist). Go up once again and copy this entire folder. For the Mozilla Suite, Firefox, or Thunderbird, this folder's name should be Mozilla, Firefox, or Thunderbird, respectively.
  3. Copy (but not move) your entire <profile folder> to another location.

(4) Using <tt> with quote marks

  1. Completely close all Mozilla programs, including the Mozilla Suite, Firefox, and Thunderbird. Don't forget to exit the Mozilla Suite's Quick Launch if it's open (as indicated in the Windows system tray).
  2. Find your profile folder. Go up in the folder hierarchy until you see the folder that contains the folder "Profiles" and the files "pluginreg.dat", registry.dat", and "profiles.ini" (not all files may exist). Go up once again and copy this entire folder. For the Mozilla Suite, Firefox, or Thunderbird, this folder's name should be "Mozilla", "Firefox", or "Thunderbird", respectively.
  3. "Copy (but not move) your entire profile folder to another location.

Proposed style guideline

Short version:

  • Path/folder/file names: In general, put these in <tt></tt> tags (e.g., C:\Program Files\Mozilla Firefox\firefox.exe). In some situations, however, especially in less-technical articles, it may look better to use simple quotation marks (e.g., "Go to your profile folder and find the "chrome" folder"). Use your best judgment, depending on the context and readability.

Long version:

  • Path/folder/file names: In general, put these in <tt> tags (e.g., C:\Program Files\Mozilla Firefox\firefox.exe). In some situations, however, especially in less-technical articles, it may look better to use simple quotation marks (e.g., "Go to your profile folder and find the "chrome" folder"). Folders whose location varies are sometimes better when enclosed in angle brackets (e.g., <profile folder>/chrome/overlayinfo/). Use your best judgment in all cases, depending on the context and readability.

Revised version (based on Asqueela's comment above):

  • Path names: Enclose these in <tt> tags so that they will appear in a monospace font (e.g., C:\Program Files\Mozilla Firefox\firefox.exe). Folders whose location varies (e.g., "profile folder" and "install folder") can be enclosed in angle brackets when part of a path (e.g., <profile folder>/chrome/overlayinfo/).
  • Folder & file names: Put these in quotation marks when they are used in a sentence but are not connected to a longer pathname (e.g., "Go to your profile folder and find the "chrome" folder").
I like this. asqueella
Thanks again for the feedback. I'll put this in the page. --wintogreen
Note that Mozcerize said he doesn't like variable width+quotes because we already were are already using it for many other things. --asqueella
Hm, it's not clear to me if he meant paths or lone file/folder names, or both. --wintogreen
Yes, that wasn't clear to me either. --asqueella
Overall I like this. Personally I prefer Example 2 over Example 1 above (ie putting filenames and folder names in <tt> with no quotes rather than in variable+quotes) but I'm happy to compromise on this. (I definitely didn't like to see path names in variable+quotes.) I guess I prefer fixed width for lone names because, as in your examples, when you have an article which lists files that a user is supposed to be looking out for (eg for copying, renaming or whatever), he is going to look at Explorer(=File manager), jump back to the browser, look at Explorer again, etc. It's easier when glancing at the article to pick out the relevant filenames from the rest of the text when they are formatted in fixed width rather than in variable+quotes—try it with Examples (1) and (2)!. But it's a small issue. --Mozcerize 00:19, 31 Mar 2005 (PST)
The style guide seems to assume that <tt> tags should be used on paths because its desireable to make them standout for readability. I understand why you want to do that in many cases, but it can cause problems. For example when your're writing a sentence that mentions a location and you don't want to draw extra attention to it. I think the prior style gudelines were better because they left some flexibility. --Tanstaafl 9:30PM, Jan 19 2006 (PST)
What prior style guidelines? --wintogreen 07:22, 21 January 2006 (UTC)
The ones just above the line "Revised version (based on Asqueela's comment above):". It includes the text "Use your best judgment in all cases, depending on the context and readability." Tanstaafl 22:17, 2 February 2006 (UTC)
OK, now I see. Even though I don't much care for the <tt> look in general, I still prefer the "stricter" guideline. The negative fallout is minimal, whereas having a looser guideline would lend itself to greater inconsistency throughout the kb. --wintogreen 05:09, 3 February 2006 (UTC)

Use of monospace font for path folder and file names

My impression is that this formating is being misused, making articles harder to misread because the text in a paragraph is frequently more visible than the header. It should apply to real pathnames (were there is a legitimate reason for wanting it to catch your eye), not every time somebody tries to explain the syntax of how to change a parameter. Its makes sense to use it for the default location of profiles or profiles.ini but not when describing the contents of a profiles.ini file for example. I'd like to modify the article accordingly. Tanstaafl 22:33, 6 February 2008 (UTC)

For the record, here are the current guidelines, from In-house_style#Special_punctuation_and_formatting:

  • Path names: Enclose these in <tt> tags so that they will appear in a monospace font (e.g., C:\Program Files\Mozilla Firefox\firefox.exe). Folders whose location varies (e.g., "profile folder" and "installation directory") can be enclosed in angle brackets when part of a path (e.g., <profile folder>/chrome/overlayinfo/).
  • Directory & file names: In general, put these in quotation marks when they are used in a sentence but are not connected to a longer pathname (e.g., "Go to the "chrome" folder in your profile folder and find the "userChrome.css" file"). Exceptions: you can omit the quotation marks around well-known file names (e.g., prefs.js or user.js), second and subsequent instances of a file name that appears multiple times in the same article, or file names used in Dev articles (you can use <tt> instead). Alice 01:57, 7 February 2008 (UTC)
I guess an example of what you consider misuse can be drawn from your recent edit of the Moving your profile folder article, where you removed the <tt> tags around some "fictitious" paths so, instead of "Create a new, empty folder in the desired profile location with the name you wish to use for the new profile, for example, D:\Mozilla\Firefox\Profiles\newprofile ... " you made it, "...<snip> for example, D:\Mozilla\Firefox\Profiles\newprofile ... " I don't agree with making a distinction between real and fictitious path names in the current guidelines since (correct me if I'm wrong!), the reason you are adding the tags is to make the path names visually stand out, and the monospace font does that. I think that making a rule distinguishing "real" and "fictitious" path names would make it needlessly complicated; for example, what about partially fictitious paths, like in the above example, <profile folder>/chrome/overlayinfo/), where "profile folder" is itself a fictitious name for the "real" profile folder, e.g., u9gre7n2.default. Anyway, instead of trying to differentiate, I'd go along with using either quotes or italics, instead of <tt> tags for all path names, fictitious or not. I never much cared for monospace font anyway. SUMO uses what looks like italicized text, by the way, for file names and paths, for example, http://support.mozilla.com/kb/Profiles#How_to_find_your_profile Alice 01:57, 7 February 2008 (UTC)
I don't think it makes sense to make a sample path in a profiles.ini visually stand out (its no more important than the other parameters), but I understand your argument about how modifying the rule could make it too complicated. Your idea of using italicized text instead of monospace font seems the best choice. It doesn't make it stand out so much that its worth arguing about real vs fictitious paths... Tanstaafl 04:22, 7 February 2008 (UTC)
The only problem I can see with switching to italics for path names is going to be lack of consistency between articles. If you don't think that's a problem then how about a simple guideline that either italics or monospace font should be used for all path names in an article, as long as you are consistent. The Directory and file names rule is OK as is, except you might want to add to the "Exceptions" that quotes aren't needed if the directory or file name is linked to an article of the same name (I don't think that any linked file name like mimeTypes.rdf or bookmarks.html ever needs to be placed in quotes). Speaking of file names, there's already inconsistency. Using <tt> tags to format file names with monospace font is done quite a bit where it isn't really needed (e.g., Profile folder - Firefox). Alice 05:02, 7 February 2008 (UTC)
I think if a dozen or two of the most popular articles were converted the lack of consistency won't be a problem. I don't mind spending some time doing that. We seem to do enough maintenance of articles that it wouldn't take that long before we reach a tipping point. I would prefer the guideline to recommend just italics (rather than say you can use either choose italics or monospace as long as you're consistent) to avoid the issue of when should you highlight pathnames.
The current rules for Directory & file names says use quotation marks, not monospace, so I don't see a inconsistency with monospace having been used for filenames in some articles. I would like to see monospace not used at all for anything. We have bold, quotes, italics, links and recently decided that we should try to avoid HTML whenever possible. I agree with your suggestion to add quotes aren't needed if the directory or file name is linked to an article of the same name to the list of exceptions. Tanstaafl 19:57, 7 February 2008 (UTC)
Path names: I would prefer the guideline to recommend just italics ...for path names, OK, I can go along with that as a guideline that would include "In general" or "In most cases", to use italics for path names, especially when used within a paragraph. We can either spell out or imply that exceptions to this rule can exist. Personally, I prefer monospace for paths (or command line arguments) that we want the user to copy, because it stands out better and is easier to read, e.g., Shortcut to a specific profile and Profile_Manager#Accessing_the_Profile_Manager. I also don't think we should use italics (or any special formatting, really) in any "code box", since the text is already visually distinct. Alice 15:46, 8 February 2008 (UTC)
Directory & file names: The current rules for Directory & file names says use quotation marks, not monospace, The current rule includes an exception that allows monospace font for file names, which I think should be removed: "Exceptions: you can omit the quotation marks around well-known file names (e.g., prefs.js or user.js), second and subsequent instances of a file name that appears multiple times in the same article, or file names used in Dev articles (you can use <tt> instead)." This rule seems to allow either no formatting or monospace font for listed exceptions (and, do we even write Dev articles any more?) The current rule also says, "In general, put these in quotation marks when they are used in a sentence...." which is important to remember. There is no need for special formatting when the file name is not part of a sentence. If file or folder names are used within a table, or even in a bullet list, I don't think any special formatting is needed. That's what I meant by unneeded monospace formatting in the Profile folder - Firefox article's use of monospace font for file and folder names. Before coming up with any new formatting guideline proposal I think we allow some time for others to add comments. I'll add a link to this discussion and to the discussion about preference name formatting to Knowledge Base changes, which I've moved to a separate section, below. Alice 14:53, 8 February 2008 (UTC)
Earlier on you had commented that you wanted to use monospace fonts for paths and command line arguments "because it stands out better and is easier to read". What about using bold instead of monospace? It stands out more and is easier to read than italics, yet doesn't use HTML or stand out more than most section headers. Tanstaafl 22:30, 8 February 2008 (UTC)
Why not make special formatting (in this case, italics) for paths and command line arguments the rule only when used within a sentence or within the text of a paragraph? That's the current rule now for file names and folders, isn't it? I could live with that, since if I wanted a path to be more prominent I could always use a bullet for the path (like in the Profile Manager article) or use a code box that included just the path (like in the Shortcut to a specific profile article) where the italics rule wouldn't apply and no special formatting would be required. Any paths or command line arguments used in tables also wouldn't need any special formatting. In other words, how about something like this:
  • Path names: In general, use italics when a folder or file path is included within a sentence or paragraph (e.g. "Open the C:\Program Files\Mozilla Firefox\plugins\ folder."). Folders whose location varies (e.g., "profile folder" and "installation directory") can be enclosed in angle brackets when part of a path (e.g., "Open the <profile folder>\bookmarkbackups\ folder.") Exceptions: No special formatting is required for path names entered in code boxes, table cells or as separate items in a list.
  • Directory & file names: In general, put these in quotation marks when they are used in a sentence but are not connected to a longer path name (e.g., "Go to the "chrome" folder in your profile folder and find the "userChrome.css" file"). Exceptions: you can omit the quotation marks around well-known file names (e.g., prefs.js or user.js), second and subsequent instances of a file name that appears multiple times in the same article, or for file names that are article links. Note that no special formatting is required for file or folder names entered in table cells or as separate items in a list.
  • Path or file names followed by command line arguments: Place the entire phrase in italics (e.g., "Go to the Start menu, open the Run dialog, type in firefox.exe -profilemanager and click OK.")
Fine with me. Lets see if anybody else comments. Tanstaafl 03:18, 9 February 2008 (UTC)
We could also have a similar rule for preferences (see below). Alice 01:05, 9 February 2008 (UTC)
I edited the above to list Path or file names followed by command line arguments as a separate item. Alice 23:38, 9 February 2008 (UTC)

Preference names

While we're at it, any thoughts on rules for formatting preference names? In the about:config entries article, they're all in bold, whether linked to preference articles or not. Other articles have them in italics, or bold, or just linked with no formatting. I'm not saying we should go back and change any of the articles for consistency, just that a guideline would be nice to have, if only for people wanting to write new articles. Alice 05:02, 7 February 2008 (UTC)
I like using bold for preference names. This article is an example where using italics or just a link would have made it harder to parse the text. I can see the merits of using italics though. I run into enough preferences that have no documentation that underlining would be an issue. Its always possible to overuse bold, but if we're getting rid of monospace fonts it would seem sensible to standardize on bold for preference names given its popularity. However, I agree with you we should not go back and change any articles to conform with whatever guideline is chosen for preference names. Tanstaafl 19:57, 7 February 2008 (UTC)
I'm going to look at a few more articles that include preference names before saying which formatting I prefer, but any new guideline should probably limit use of special formatting to preference names that are included within the text of a paragraph. I don't think there is any need for special formatting for preference names (or for paths, folder and file names) that are included in a list or table. Alice 14:53, 8 February 2008 (UTC)
The only problem with placing preference names in bold would be that it might be confusing, since user-set preferences appear in bold in about:config. If you do want to go with bold, then how about limiting it to preferences included as part of a sentence, but not for preferences included in a table or list. That way it will cut down on the bold text in an article. I was thinking of something like this:
  • 'Preference names and values: In general, put these in bold text when they are used in a sentence or paragraph (e.g., "Use about:config to set the network.cookie.cookieBehavior preference to 1.") Exceptions: No special formatting is required for preference names that link to articles. Note that no special formatting is needed for preference names and values that are entered in table cells or as separate items in a list.
Alice 01:05, 9 February 2008 (UTC)
Fine with me. Lets see if anybody else comments. Tanstaafl 03:21, 9 February 2008 (UTC)

I edited In-house style#Special punctuation and formatting based on the above. Alice 14:32, 19 February 2008 (UTC)

File names, pt.2

Proposed addition: one can omit quotes when writing about a file is, um, "famous", eg. 'Add this to your user.js', but 'Open "user.js" in your profile folder'.

Also I think we can live without filenames in quotes in dev. section. I feel stupid when I write 'you need to edit "install.rdf" to do that'. I think the dev section will eventually be moved to devmo anyways..

We could use variant 2 from the above section, ie. with >tt<, but without quotes for that. Note, that I still think that using quotes around file names in other cases is fine. --asqueella 07:08, 17 Apr 2005 (PDT)

I agree --Mozcerize
When I was editing a bunch of pages recently, I also felt it was overkill putting every single instance of a filename in quotes, much like linking every single instance of a term becomes an annoyance. Maybe we could amend the style guideline thus:
Directory & file names: In general, put these in quotation marks when they are used in a sentence but are not connected to a longer pathname (e.g., "Go to the "chrome" folder in your profile folder and find the "userChrome.css" file"). Exceptions: you can omit the quotation marks around well-known file names (e.g., prefs.js or user.js), second and subsequent instances of a file name that appears multiple times in the same article, or file names used in Dev articles (you can use <tt> instead).
(wintogreen)
Nice. We'll see how it works. (I once again feel like a punctuation nazi.) --asqueella 04:01, 18 Apr 2005 (PDT)
OK, I'll add it to the page. But... I thought hao2lian was the punctuation nazi. Or was he the grammar nazi? It gets so confusing sometimes.... --wintogreen

Links

I think something like the following should be added to the style rules. (and yes, I'm lazy, so I just copied it from another wiki) --asqueella

Don't overdo linking. That's the extreme opposite of not linking at all. It's most convenient for authors and readers alike to link only the first occurrence of a term in a logical unit (a section of a tutorial, for instance). Since links stand out visually, they have the potential to disrupt the reader's flow and make reading a long text a pain when each and every sentence has one or more links. For example, if you mention "profile folder" several times, link only the first one, or the one that's relating to something technical, at a point where the reader might logically want to read up on the specifics.
Good idea. Below is a somewhat shorter rewrite. --wintogreen
Don't overdo linking. Since links stand out visually, they can disrupt the reader's flow and become a distraction rather than an aid. Try not to put the same link more than once in a single logical unit of an article (e.g., a section of a tutorial). For example, if you mention "profile folder" several times, link only the first one, or the one that's relating to something technical, at a point where the reader might logically want to read up on the specifics.

Thanks! I added your version to the article. --asqueella

Uploading Screenshots

I would like to request the ability to upload screenshots. Images make understanding instructions a lot easier. The cases which immediately come to mind are:

  • How to customize the toolbars
  • How to modify your Privacy settings
  • How to edit your preferences (about:config)
  • How to edit your userChrome.css file
  • How to configure Tabbed Browsing
  • How to create a new Firefox profile

etc. --Emte

You need to ask kerz about that. -asqueella


Linking to Bugzilla

Has anyone thought up a policy for linking to Bugzilla. I'm not sure if it's appropriate to put these links in the article text, e.g. This is a known issue, Bug 1000 or if it's best to just add the Bug link to the External Links section. --Gids

Good question. At the moment, several articles link to Bugzilla in the form there is a bug in Firefox where if… which is coded as a [http://bugzilla.mozilla.org/show_bug.cgi?id=261031 bug] in Firefox. I agree that it could be inappropriate to link to such technical documentation in the text. I think it would be better to make use of footnotes in the External Links section, e.g. use there is a bug [1] in Firefox where if… in the text, which links to the footnote at the bottom, such as
This is coded using a bug [[#foot1 | [1]]] in Firefox and <div id="foot1">[1] [http://bugzilla.mozilla.org/show_bug.cgi?id=261031 Bugzilla report 261031].
Apologies for the bolding; obviously this is to indicate article code here, and shouldn’t be used in the actual article! Mozcerize 01:18, 13 September 2005 (PDT)

Introductory paragraphs - header or no

Compare Profile in use to Profile Manager. One had the intro the "Background" heading, the other just puts it at the top. Which is better? Personally, I like "just put it at the top".--Np 19:49, 6 December 2005 (UTC)

I prefer to not have the intro separated from the rest of the article by the TOC, but I don't like using a meaningless header to push the intro down. Is TOC placement a wiki pref that can be easily tweaked? --wintogreen 22:06, 6 December 2005 (UTC)
I actually prefer it that way.. it's the way Wikipedia works too. But it's not really something that can be debated, it's more personal preference. Put it to a vote?--Np 22:46, 5 January 2006 (UTC)
Having the intro in a background heading in Profile in use looks better than having it at the top in Profile Manager. But I've seen other cases where having it at the top looked better. I think it depends upon the length of both the intro and the TOC. I suggest we leave it to the authors best judgement. --Tanstaafl 9:52PM , 19 January 2006 (PMT)

Layout of headers

IMHO the layout of headers in our kb should have more space above and below each header, to set them apart and make it easier for people to skim the page. Long KB pages look cluttered and are hard to skim.

At first I thought Wikipedia used more negative space, but looking closely I see we seem to match their layout exactly. I think they just have a different kind of information to lay out, long paragraphs, while we have many lists, short paragraphs, short sections, etc.

I don't know how easy it is to change the basic template, so perhaps it's not worth the time and effort. But the space is free (we're not paying for paper) and using 'negative' space for such purposes is very common.

--guanxi 12:08, 19 Jan 2006 (Thu) EST
I've often wished the level 2 headers had a bit more padding on top. --wintogreen 19:26, 19 January 2006 (UTC)

Common terms

Currently we capitalize things which we regard as proper nouns: Global Inbox, Download Manager. What do we do regarding Bookmarks, History, Download History? --Mozcerize 17:15, 2 February 2006 (UTC)

If it's the feature of Firefox, it's capitalized. "Download Manager" is a feature. "download history" is information. You use the Download Manager to see the download history. You use the Boomark Manager to see bookmarks. You use the Preferences Dialog to change preferences.--Np 17:46, 2 February 2006 (UTC)
I agree: capitalize things that seem to be named product features (or major, named UI elements) but not the more generic-sounding items that are managed with these product features/UI elements. I would thus only capitalize something like "Download History" if I were quoting it in a menu sequence, such as "Tools -> Options -> Privacy -> Download History", where it's shown capitlized in the UI. --wintogreen 17:51, 2 February 2006 (UTC)
That was the point I was getting at, really. I agree with Wintogreen's proposal. --Mozcerize 11:31, 3 February 2006 (UTC)

Notes, warnings, hints

Many, many articles have

  • Note/warning/hint: blah blah blah

I feel this distracts from the flow of the articles. From what I've seen, it's mainly used as a crutch to put unrelated stuff into existing information. I believe we should "frown upon" this construct.--Np 17:58, 31 July 2006 (UTC)


Notes can be used, for example, to avoid impending disaster and other adverse outcomes, or to alert the user to info he/she might otherwise be too thick-headed to notice. Examples:
  • Note: JavaScript is not Java.
[Strictly speaking, this is more than the minimum information required, but we sure don't want to remove it, do we?]
To eject the cache from the main frammitz, delete the 'Foo' subdirectory.
  • Warning: do not delete the entire BlahBlah directory or disaster will ensue.
[Here we have the benefit of hindsight. If we leave out warnings, disaster will ensue.]
One could omit the word "note" or "warning", leaving only the bullet, but there are times when it might be nice to point out the difference.


Hints can be used as a way to tell an easy way to accomplish something complicated. They might be especially appropriate if a list is not a good choice because it would consist of only one item. Example:
  • Hint: If you do not know how to respork the frazz, and you are so incompetent that you don't know how to carry out the following 27 steps, get help.
[Yes, I know, this one is too long. It's a humorous example.]
It seems to me that paragraphs and lists don't convey all the information that needs to be conveyed in the eye-catching way that is sometimes needed. Hints, notes, and warnings not the only way to do things, but it works, in my opinion.--AnotherGuest.
JavaScript includes a note without the *Note: syntax just fine. You don't need to prefix notes with a bullet point and the word note, just say them. As far warnings, bolding is a much better way to get things noticed. I don't understand the need for hints. If something is complicated, don't tell the user to do it then provide hints, just explain how to do it. Rather than "Hint: If your firewall still blocks access after being configured, try rebooting the computer.", say "If your firewall still blocks access after being configured, reboot your computer." If the explanation is too long to include in the text, you can create a new article like we did for ending Firefox processes.--Np 20:50, 31 July 2006 (UTC)
I don't understand why inline text is not supposed to disrupt the flow, but bullets well placed outside the paragraph are supposed to be disruptive, even if they present crucial information. I don't agree, but maybe that's just me. I also worry about bold text, with various combinations of fonts and visual impairment. I also note that the KB style notes discourage use of bold. So we're supposed to use it and we're not. If you don't want bullets, we need a clear statement of style before people post. A lot of time goes into writing this stuff if it's done carefully.
Maybe people can make up their minds better if the see the Firewalls article in question.
The JavaScript note appeared (appears) in various places, and it worked. It's a short note, exactly where people need to see it. Before that note was placed in KB, we used to get a lot of extra support messages where people had made mistakes and were advising other people to make the same mistake. --AnotherGuest.

What exactly is the objection? Is it the bullets that you want to avoid when using the words "Note" "Warning" or "Hint" to preface a point, or is it the use of these words in and of themselves? Only a few pages include "hint" to preface a point. Upgrading (Thunderbird) has Hint to newbies: and Import address list from text file has Additional hint: but only the Firewalls article includes "Hint" with a bullet. Lots more pages use "Warning" to introduce an important comment ... isn't this analogous using the "Caveats" heading in preference articles ("caveat" just means a "warning" or "caution" [2]) such as Browser.bookmarks.file? DOM Inspector has Warning! Toolbar customization - Firefox just has Warning! (with no formatting). Warning: prefaces important caveats in About:config and Profile Manager (twice). "Note:" is even more frequent ... Uninstall search plugins uses *Note: and Mozilla Suite : FAQs : Installing A New Version uses Note! to open the article! If it's also a matter of formatting the text, or what punctuation to use following the prefacing word, maybe there should be some consistency such as whether to italicize or use bold text to preface these hints, notes and warnings, and whether a colon rather than exclamation point should follow the prefacing word? Also, what about Important:? That's also used to preface, well, important points.. Alice Wyman 13:50, 1 August 2006 (UTC)

My objection is to sentences prefaced with "Note:" and "Hint:" (just say what you want to say, the word note or hint isn't adding anything), and to bullet points for both of those and "Warning" (bullet points aren't for formatting, they're for making an unordered list). "Warning: " is fine style-wise to me. --Np 14:37, 1 August 2006 (UTC)
I can live with that. Alice Wyman 15:30, 1 August 2006 (UTC)
Right. "Note" is unnecessary if other attention-getting devices (e.g., bold face) are permitted. And I'm certainly not wedded to the word "hint".--AnotherGuest.
Bold face is permitted per the in-house style, but should be used sparingly. Warnings are a very good reason to use bold text, as is something that is potentially confusing or unexpected and is important for the reader to know (ex: Closing the firewall doesn't turn it off).--Np 16:41, 1 August 2006 (UTC)

Use of slang or technical jargon

I think that slang or technical jargon should be avoided, if possible, especially if the term's meaning may not be clearly understood by the average user. Case in point: "gotcha", which was recently added here: Firewalls#Firewall_gotchas as a section heading. Alice Wyman 14:54, 2 August 2006 (UTC)

Use of color

Somewhere this evening I read that html isn't supported which is not true on MediaWiki...Wiki formatting is preferred but as not all html tags are supported html is also supported for those times. I have already seen one article using the colors green and red. My current main contribution to the KB here is also using "some color", specifically gray scale to denote sections that aren't that important (like a comment) and red for extreme emphasis (I use this very lightly). I do like color when reading but not too much because it can be distracting if it's overused. I specifically didn't include my "GREEN" colors from The Linux, the Logitech and the Firefox] because the majority of articles here didn't have color... so now I need some clarification on opinions for use of color. Obviously wikilinks and external link colors shouldn't be used as they may confuse anyone visiting the KB unless it's a chrome URI, in which case it won't open anyways... but will still indicate that it's a valid link. Anyhow... enough rambling on... please let me know. Thanks. Martimus8 09:19, 11 January 2008 (UTC)

My current main contribution to the KB here is also using "some color" which I take it you mean Linux and the mouse where you've added grey scale and red text with HTML, and in which you've included a link to your forum post, The Linux, the Logitech and the Firefox. To tell the truth, the only colored text I remember seeing in KB pages are the warnings to users not to post questions on article Talk pages, for example, Talk:Knowledge Base (which you've seen already, since you recently posted a comment there). I don't think we should be expending energy adding colored text to articles, plus it makes it more complicated for other users who might not be that experienced with HTML to later edit the page (and that includes me!). I'm going to post a link to this discussion in Knowledge Base changes for other opinions. You're free to color up your own User page, though :) Alice 22:20, 13 January 2008 (UTC)
Between <tt>tags , bold, italics, tables, headers etc. there is no shortage of ways of drawing attention to something. If anything we seem to be overusing it (the convention of always using <tt> tags for filenames for example frequently makes a article harder to read IMHO). I don't think we should add color in the articles - the benefits aren't worth the potential problems.
I'd also argue for discouraging (but not banning) the use of HTML. The wiki markup has a <pre> tag that works as the combination of <nowiki> and the standard HTML <pre> tag. Other than <tt> tags the main use of HTML seems to be for the occasional table. The wiki markup tags for tables seem pretty useful (and easier to comprehend if you don't know HTML) . I'd like to add a statement to the style guide explicitly banning color and discouraging (but not banning) HTML. Any objection? Tanstaafl 00:41, 14 January 2008 (UTC)
I think HTML should be discouraged when there exists a Wiki way of obtaining the same result, and, indeed, that it should not be banned. The author may be unfamiliar with the particular Wiki markup, or (as, IIUC, for underlining) there may be no specific Wiki markup. -- Tony 01:08, 14 January 2008 (UTC)
— P.S. About color, I think color should be avoided in principle (but might be used in special cases, if there exists a very good reason to use it), especially since there are a number of different "skins" available to logged-in users, which considerably change the "look and feel" of the pages, and that it is not obvious that a given "special" text or background color will look good in all skins. I'm not defining what is or isn't "a very good reason"; I hope contributors will exercise sane judgment. -- Tony 01:15, 14 January 2008 (UTC)
I have no objection to adding a statement to In-house style (and to MozillaZine Knowledge Base:Formatting, if appropriate) which discourages the use of HTML where Wiki markup can obtain the same result and which bans or strictly limits colored text and background color, with an exception made for ones own to User page(s). Alice 01:44, 14 January 2008 (UTC)
Created In-house_style#Markup_language Tanstaafl 09:05, 14 January 2008 (UTC)

Keeping this article about style

A section was recently added about Removing obsolete information. I think that section really belongs in the Rules and guidelines article, which already has a section about Quality and subsection about Technical information. Also, the first section about Articles that apply to more than one application isn't really about style (except for the comment that combined articles can get messy) but is more of a suggestion to create or edit articles so that they apply to more than one application. I think that "Removing obsolete information", and probably "Articles that apply to more than one application", should be moved to Rules and guidelines. Alice 12:57, 11 February 2008 (UTC)

Copied from Knowledge Base changes#Removing obsolete information (which includes the background) Alice 14:51, 11 February 2008 (UTC):
If we did move it the Quality section doesn't seem appropriate - its own section would be the best bet. We have text about how to make an article more usable in both articles, so I guess its really a question of whether you think it falls in to the guidelines or the look consistent camp. I prefer the current location, but it doesn't really matter. I have no problem with you moving it after waiting a couple of days to see if anybody else has a opinion. Tanstaafl 13:54, 11 February 2008 (UTC)
OK, I'll wait a few days then move "Removing obsolete information" from this article to its own section in the Rules and guidelines article. What about the "Articles that apply to more than one application" section? I also think that should be removed from this article and added to Rules and guidelines as a new section. That way, this article would be strictly about style considerations (common names and terms used, special formatting and punctuation, use of HTML, tables, headers, etc.) or, in other words, about how KB articles look as opposed to what information they contain. If you like, I could keep both of the old section headers in this article but replace the content with links, just like the Rules and guidelines article has a Style guidelines section that links here. Alice 14:51, 11 February 2008 (UTC)
You might as well move it too, using its own section. Thanks, but I think keeping the old section headers (and adding links) would just confuse things. Its better to have a clean separation. Tanstaafl 23:35, 11 February 2008 (UTC)

I removed In-house style#Removing obsolete information and In-house_style#Articles that apply to more than one application and will place those sections in Rules and guidelines and refer to this discussion on that article's talk page. Alice 14:32, 19 February 2008 (UTC)