62642 - Write a FAQ for Web authors

Status: VERIFIED FIXED

(Documentation Graveyard :: Web Developer, defect, P3)

Description

[Henri Sivonen (:hsivonen)]

We need a FAQ for Web authors. Initial draft coming up.

Comment 1

[Henri Sivonen (:hsivonen)]

Attachment: First draft

Comment 2

[Gervase Markham [:gerv]]

Can we use http://sites.netscape.net/ekrockhome/standards.html ?

Gerv

Comment 3

[rudman]

Adding dbaron to cc list.

Comment 4

[HJ]

What they need is examples, because FAQ's are just copies of W3C doc's. So
direct them to a validator for HTML and CSS validation. And then again, where to
locate examples? I did a little search, and it seems that good working example's
for DOM 0/1/2 (and CSS) are very hard to locate. If you provide this kind of
information, that's exactly what web authors need.

And just redirecting them to ECMA and/or W3C is a start, but that's not more
than that.  Or are you ready for this one: "just take a look at 'the garbage' of
other web authors".

Friendly, HJ.

Comment 5

[Henri Sivonen (:hsivonen)]

Attachment: Second draft with links

Comment 6

[David Baron :dbaron: (⌚️UTC-4, no longer working on Mozilla)]

Some quick comments:

Numbering would be nice.  I'll assume it's there. :-)

#1) Once the mode deciding code is improved (hopefully RSN...), I'd like to
reword this.  What we really want to do is use the DOCTYPE as a heuristic to
indicate new vs. old documents, but still allow authors an authoritative way to
override that heuristic.  It would also be good to briefly explain the intent of
the two modes:  quirks mode differs from standards mode where implementing the
standards correctly would break significant numbers of existing pages.

#2) I'd like to provide more details on this one in the future...

#3) It seems to me all the points other than the first two should be sublists
under the first two, except for 7, 10, and the last two, which deal with XML (is
there a good online XML validator?  And does <link /> work in XML?  (Should it?
-- see my comments on other bugs.)).

Comment 7

[Henri Sivonen (:hsivonen)]

Attachment: Third draft

Comment 8

[Henri Sivonen (:hsivonen)]

* Added hard-coded numbering (Mozilla doesn't support CSS outline numbering yet)
* Moved some list items into sublists
* Fixed a typo

"instead or <link />" was a typo. I meant "instead of". <link /> does not work with text/xml 
content. I'm inclined to believe it should not work with text/xml, but I am not 100% sure.

Comment 9

[Henri Sivonen (:hsivonen)]

Attachment: Fourth draft with two new questions

Comment 10

[fantasai]

For Quirks vs. Standard, you need to include
  - the fact that XML is always rendered Standard
  - how to use Quirks with a validating HTML document

Comment 11

[Gervase Markham [:gerv]]

henris: feel like sprucing this up? We might need it reasonably soon...

Gerv

Comment 12

[rudman]

Fyi---Ellen Evans (adding to cc list) is writing about XSLT support, and should
have a draft available soon.

Comment 13

[Henri Sivonen (:hsivonen)]

Attachment: Fifth draft

Comment 14

[Henri Sivonen (:hsivonen)]

New version attached.

fantasai, I don't think telling how to validate quirky docs is appropriate. That
would make it look like activating the quirks mode was desirable. I think the
message should be that the standards mode is the way to go if you have come far
enough to read the FAQ.

Comment 15

[Henri Sivonen (:hsivonen)]

Can anyone come up with question that are not yet answered but should be?

Should I change to links that point to ekrock's old pages to links pointing to
other mozilla.org docs? If so, which ones?

Comment 16

[Henri Sivonen (:hsivonen)]

Attachment: Sixth draft with minor fix (tag vs. element)

Comment 17

[Gervase Markham [:gerv]]

> The Quirks mode mimics the behavior of Netscape Navigator 4.x

And some IE quirks, I think. How about "version 4 browsers"?

> * Class names and ids are case-sensitive.

...in standards mode.

> propriertary

proprietary.

> Also, please remember to not use an outdated client sniffer to shut out new 
> browsers.

Link to the ultimate client sniffer?

> layout can be changed by explicitly setting

Why not give explicit sample code that changes all images to "block"?

Eric Krock's page should have internal anchors; you might want to use them for
your two links. And perhaps a few websites under the Further Information link
wouldn't go amiss.

Gerv

Comment 18

[David Baron :dbaron: (⌚️UTC-4, no longer working on Mozilla)]

The Quirks mode should only mimic IE5/Nav4 when doing so is needed to get
significant numbers of real pages to display correctly.  Otherwise it should
also stick to standards.

Comment 19

[Henri Sivonen (:hsivonen)]

>> The Quirks mode mimics the behavior of Netscape Navigator 4.x
>And some IE quirks, I think. How about "version 4 browsers"?

I don't like "version 4 browsers". It implies that there are only the two (you don't mean Opera 4, right? :-). It 
also implies that browser version numbers are commensurable.

How about "legacy browsers"?

>> * Class names and ids are case-sensitive.
>...in standards mode.

I'd rather not emphasize that.

>> propriertary
>proprietary.

OK.

>> Also, please remember to not use an outdated client sniffer to shut
>> out new browsers.
>Link to the ultimate client sniffer?

I'd rather not point people to a script that assumes some fixed set of existing browsers. I think standard-
compliant script should be fed to any browser that advertises the existence of the applicable DOM objects--
regardless of the name of the browser.

>> layout can be changed by explicitly setting
>Why not give explicit sample code that changes all images to "block"?

I guess making all images blocks is usually harmless--but may not always be. It would also fail to change the 
surrounding <a>s to blocks.

Perhaps something like http://www.hut.fi/u/hsivonen/standards#the-solution or a link pointing there?

>Eric Krock's page should have internal anchors; you might want to use 
>them for your two links. 

OK. BTW, are there similar actively maintained docs at www.mozilla.org?

Comment 20

[Henri Sivonen (:hsivonen)]

I renamed the anchor on my page. It is more descriptive now:
http://www.hut.fi/u/hsivonen/standards#img-display-block

Comment 21

[Gervase Markham [:gerv]]

> I'd rather not point people to a script that assumes some fixed set of 
> existing browsers.

It doesn't totally; it sets vars like ie5up and ns6up which you can use for
forwards compatibility. Getting people to use that is far, far better than them
writing their own.

> Perhaps something like

Yes :-)

> BTW, are there similar actively maintained docs at www.mozilla.org?

I wish. Hopefully in the new world.

Gerv

Comment 22

[Henri Sivonen (:hsivonen)]

Attachment: Seventh draft

Comment 23

[Henri Sivonen (:hsivonen)]

Sorry for the delay.

>> I'd rather not point people to a script that assumes some fixed set of 
>> existing browsers.

>It doesn't totally; it sets vars like ie5up and ns6up which you can use for
>forwards compatibility.

That still contains the assumption that there are two browsers and that the
identity of the browser is more important than the DOM methods it implements.
What about Opera or Konqueror (or iCab and OmniWeb if they ever implement the DOM)?

(Check out http://www.hut.fi/~hsivonen/test/dom/show-hide-combined-text-js.html
for a show/hide "layer" implementation that supports three object models and
doesn't check for the browser name.)

Are we otherwise in agreement over the FAQ content?

Comment 24

[Ellen Evans]

Re:
>Also, please remember to not use an outdated client sniffer to shut out new 
>browsers.

Whatever the merits of types of sniffing, the syntax on this sentence could use
some help.  As it is written, it could be parsed to mean that one shouldn't use
an outdated sniffer only in the case that one wished to shut out new browsers.
Probably the simplest answer would be to place the main clause in the
affirmative:    "Also please remember that outdated client sniffers may shut out
new browsers, so be sure to use an up-to-date one."   Or something along those
lines.

As to XSLT support:  at the moment the processor is not fully compliant,
although they are working on it.  A document indicating what is and is not
implemented is in the final review stages and will soon be up DevEdge.

Comment 25

[Gervase Markham [:gerv]]

> * Class names and ids are case-sensitive.

... in standards mode.

> Also, please remember to not use an outdated client sniffer to shut out new 
> browsers.

After you reword this sentence, how about linking to a suitable client sniffer?

Other than that, great. I want to see this on www.mozilla.org ASAP :-)

Gerv

Comment 26

[Henri Sivonen (:hsivonen)]

Attachment: Eight draft

Comment 27

[Henri Sivonen (:hsivonen)]

I mentioned that the support for XSLT is imcomplete. I also clarified the JS
client sniffer part and added a simple code sample there. I didn't add a link to
a client sniffer, though, because I think checking for the browser identity as
opposed to browser features goes against the point of having a standard.

There are already sites that let only Netscape 6 execute DOM code. Let's not
encourage that kind of behavior.

Comment 28

[Gervase Markham [:gerv]]

> if(document.getElementById) {
>   /* code that uses document.getElementById() */
> }

AIUI, this will cause JS Strict errors. Is "if (getElementById in document)"
supported in enough browsers to be usable as an alternative?

Gerv

Comment 29

[Henri Sivonen (:hsivonen)]

Yes, if(document.foo) causes a strict warning (but not an error). What's the
meaning of the warning? Does it mean "This might be a problem if you didn't do
it on purpose." or does it mean "No, no, don't do that in any case."?

If I use (getElementById in document) in an expression where I'd normally use
(document.getElementById), I get a JS error in Mozilla and the script stops
executing.

Comment 30

[Gervase Markham [:gerv]]

Don't let this tiny thing hold up the publishing of this :-) It's not worth
worrying over.

Gerv

Comment 31

[Henri Sivonen (:hsivonen)]

Attachment: Check-in-ready version

Attached an unstyled version without the "draft" markings. Fixed one typo and
replaced "PIs" with "processing instructions". Added a link to
http://www.mozilla.org/docs/web-developer/quirks/

Gerv, May I bother you with the check-in? (What would be the correct location?
http://www.mozilla.org/docs/web-developer/faq.html perhaps?)

Comment 32

[Henri Sivonen (:hsivonen)]

Comment on attachment 57640 [details]
Check-in-ready version

Oops. A couple of markup error there. This is embarassing.

Comment 33

[Henri Sivonen (:hsivonen)]

Attachment: Really a check-in-ready version

Markup errors fixed.

Comment 34

[Gervase Markham [:gerv]]

Checked in at the URL suggested. I'll leave it up to you to post to the
newsgroups to advertise its existence.

Gerv

Comment 35

[David Baron :dbaron: (⌚️UTC-4, no longer working on Mozilla)]

I added it to the web developer docs index, and I changed the section name from
"Miscellaneous" to "Writing for Mozilla" since that's what it was.  I'm also
wondering whether to move that section up to the top...

Comment 36

[Henri Sivonen (:hsivonen)]

Thank you. I posted to n.p.m.general and .documentation.

Comment 37

[Daniel Wang]

v