MozillaZine

Talk:In-house style

From MozillaZine Knowledge Base

(Difference between revisions)
Revision as of 06:00, 20 January 2006
Tanstaafl (Talk | contribs)
(Introductory paragraphs - header or no)
<-- Previous diff
Revision as of 07:22, 21 January 2006
Wintogreen (Talk | contribs)
(Path, folder and file names)
Next diff -->
Line 116: Line 116:
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). [[User:Asqueella|asqueella]] 03:29, 29 Mar 2005 (PST) 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). [[User:Asqueella|asqueella]] 03:29, 29 Mar 2005 (PST)
-==folder and file names==+==Path, folder and file names==
I think it was decided to use <nowiki><tt></nowiki> 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 [[Thunderbird : FAQs : Changing Mail Storage Location|test case]] where I used <nowiki><tt></nowiki> for folder names without quotes. Doesn't look great to me. Ideas? --wintogreen I think it was decided to use <nowiki><tt></nowiki> 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 [[Thunderbird : FAQs : Changing Mail Storage Location|test case]] where I used <nowiki><tt></nowiki> 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. :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.
Line 167: Line 167:
:::::::Overall I like this. Personally I prefer Example 2 over Example 1 above (ie putting filenames and folder names in &lt;tt&gt; 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&mdash;try it with Examples (1) and (2)!. But it's a small issue. --[[User:Mozcerize|Mozcerize]] 00:19, 31 Mar 2005 (PST) :::::::Overall I like this. Personally I prefer Example 2 over Example 1 above (ie putting filenames and folder names in &lt;tt&gt; 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&mdash;try it with Examples (1) and (2)!. But it's a small issue. --[[User:Mozcerize|Mozcerize]] 00:19, 31 Mar 2005 (PST)
:::::::: The style guide seems to assume that <nowiki><tt></nowiki> 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. --[[User:Tanstaafl|Tanstaafl]] 9:30PM, Jan 19 2006 (PST) :::::::: The style guide seems to assume that <nowiki><tt></nowiki> 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. --[[User:Tanstaafl|Tanstaafl]] 9:30PM, Jan 19 2006 (PST)
 +::::::::: What prior style guidelines? --[[User:Wintogreen|wintogreen]] 07:22, 21 January 2006 (UTC)
== File names, pt.2 == == File names, pt.2 ==

Revision as of 07:22, 21 January 2006

Contents

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)

-> 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 &rarr; (→)? 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

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 (&lsquo; [‘], &rsquo; [’], &ldquo; [“], &rdquo; [”]) 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 (&rsquo; [’]) instead of a single neutral quote (') or the equivalent (and hence completely misnamed) entity &apos; 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 <kbd> element is a good idea - just think about all the times you'll have to type: <kbd></kbd>... --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 <kbd> 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 "[http://  ]" 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://www.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)

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

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)

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)

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]</div>.
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)