FAQ Clean-Up

[dhtml]

Here high level overview of what I want to change in the FAQ:

1) Small adjustments to the markup (more semantic/concise).
2) Fix the resources section by organizing it into lists for:
EcmaScript Resources
DOM Resources
Browser Documentation
JavaScript Library Groups (Google Groups) [New]

There may be some disagreement about including google groups links to
things like Prototype.js or jQuery google group. The reasoning behind
that is we do in fact get a good number of questions on the list where
the OP wants nothing more than to "make it work" using jQuery. A link to
the library's group would help direct those who are looking for that, so
that they can ask their question in a more appropriate place.

3) Fix technical errors and bad code and reword a few things. (The FAQ
is very long and too verbose in places.)


--------------------------------------------------
1) Small adjustments to the markup (more semantic/concise).

Replace:

from: <h3>
<a name="FAQ3_2"> 3.2 What online resources are available?</a>
</h3>
to: <h3 id="FAQ3_2">text</h3>

from: AJAX
to: <abbr title="Asynchronous JavaScript and XML">Ajax</abbr>

from: clj
to: c.l.javascript
--------------------------------------------------


Those are my suggestions. I'd like to start with the 'Resources' section
and adjust the markup. I'll post my suggestions for the technical
content in subsequent threads.

Garrett

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]>
, Wed, 1 Oct 2008 10:23:36, dhtml <[email protected]> posted:

Did I miss an announcement of an appointment
while my preferred news service was broken?

There may be some disagreement about including google groups links to
things like Prototype.js or jQuery google group. The reasoning behind
that is we do in fact get a good number of questions on the list where
the OP wants nothing more than to "make it work" using jQuery. A link
to the library's group would help direct those who are looking for
that, so that they can ask their question in a more appropriate place.

A subsection which was a more tactful version of "GO AWAY! <list of
appropriate directions>" would indeed be appropriate.

from: clj
to: c.l.javascript

While the pseudo-word clj should not be used (though CLJ is acceptable),
there seems no point in going three-quarters of the hog to the ugly
c.l.javascript - use comp.lang.javascript, CLJ, or c.l.j for it. I use
CLJ.

Please remove from the FAQ all CSS that affects the display within
ordinary text paragraphs such as in Sec 2.1. In informative technical
material, text formatting should be as the reader has chosen. Also,
don't change the <pre> <tt> <code> font.

Code within paragraphs should always be in <code> or <tt>, as in Sec 4.4
but not as in 2.3 para 2, 4.6, 4.7 end, and maybe elsewhere.

It is rather annoying when text just stops and one has to think, however
briefly, as to whether that's the end. At a minimum, please try <hr>
after "checks the links." I use

body { color: black; background: #FFFFB0; font-size: 100%;
margin: 0; padding: 1ex;
border-top: ridge lime 1ex; border-bottom: ridge lime 1em; }

but please don't use exactly those colours - moderately similar is fine.

<Hn> markup is misused in the list before Section 1; it should be a
List.

Clarify the status of the Notes. Your FAQ should say whether or not you
maintain them, and if not then who does.

Take the whole browser view, and copy'n'paste into Word or similar.
Most of its grammar/spelling suggestions will be wring, but some will be
right.

Omit trailing whitespace !

FAQ 2.2 title is negative; change to "What questions are on-topic for
CLJ?".

FAQ 2.2 "What do I have to do before posting to clj? " to "2.3 What
should I do before posting to CLJ?"

FAQ 2.11 Subject - move first sentence into some paragraph.

FAQ 3.1 "The errata should be considered a must read along with the
book." is ugly. "The errata should be read along with the book.".

FAQ 3.2 : use Lists.


In order not to overload yourself or your reviewers, I suggest that much
of the editing of each section should be done after Bart has posted it
cyclically; once it is known that FAQ updating is in hand, regulars will
be able to propose changes after seeing the daily section.


Firefox 2 is 2.0.0.17.

 

[dhtml]

In comp.lang.javascript message <[email protected]>
, Wed, 1 Oct 2008 10:23:36, dhtml <[email protected]> posted:

Did I miss an announcement of an appointment
while my preferred news service was broken?



A subsection which was a more tactful version of "GO AWAY! <list of
appropriate directions>" would indeed be appropriate.

What do you mean?

While the pseudo-word clj should not be used (though CLJ is acceptable),
there seems no point in going three-quarters of the hog to the ugly
c.l.javascript - use comp.lang.javascript, CLJ, or c.l.j for it. I use
CLJ.

OK.

Please remove from the FAQ all CSS that affects the display within
ordinary text paragraphs such as in Sec 2.1. In informative technical
material, text formatting should be as the reader has chosen. Also,
don't change the <pre> <tt> <code> font.

There's no css for the display of <p>. We have:

p {
font-size: 100%;
margin-bottom: 0.5em;
margin-left: 2.5em;
margin-top: 0.5em;
}

(inherited values
html {
color: #000000;
font-family: sans-serif;
}

I'd like to remove margins (which have been applied to all the block

Code within paragraphs should always be in <code> or <tt>, as in Sec 4.4
but not as in 2.3 para 2, 4.6, 4.7 end, and maybe elsewhere.

It is rather annoying when text just stops and one has to think, however
briefly, as to whether that's the end. At a minimum, please try <hr>
after "checks the links." I use

body { color: black; background: #FFFFB0; font-size: 100%;
margin: 0; padding: 1ex;
border-top: ridge lime 1ex; border-bottom: ridge lime 1em; }

If body has some margin, it can give a little space. Its a little easier
on the eyes.

but please don't use exactly those colours - moderately similar is fine.

No worries :-D

<Hn> markup is misused in the list before Section 1; it should be a
List.

I agree. I will make this change.

Clarify the status of the Notes. Your FAQ should say whether or not you
maintain them, and if not then who does.

Where is the 'status of the notes'?

Do you mean: 5.2 How do I make a suggestion?

Take the whole browser view, and copy'n'paste into Word or similar.
Most of its grammar/spelling suggestions will be wring, but some will be
right.

Omit trailing whitespace !

from ?

FAQ 2.2 title is negative; change to "What questions are on-topic for
CLJ?".

Done. Does the answer seem too lengthy?

FAQ 2.2 "What do I have to do before posting to clj? " to "2.3 What
should I do before posting to CLJ?"

That's 2.3 - 2.3 What do I have to do before posting to clj?

Changed to :
What should I do before posting to CLJ?

Does the answer seem a little verbose?

FAQ 2.11 Subject - move first sentence into some paragraph.

FAQ 3.1 "The errata should be considered a must read along with the
book." is ugly. "The errata should be read along with the book.".

Done.

FAQ 3.2 : use Lists.

Agreed.

I have gone over that list a lot. I have a few lists for that. As I
mentioned in the first post on this topic, four lists:
EcmaScript Resources
DOM Resources
Browser Documentation
JavaScript Library Groups (Google Groups) [New]

It's on my local drive.

In order not to overload yourself or your reviewers, I suggest that much
of the editing of each section should be done after Bart has posted it
cyclically; once it is known that FAQ updating is in hand, regulars will
be able to propose changes after seeing the daily section.

Cyclically? I'll have to get in touch with Bart, then. The changes you
suggested are not live.

I've made a few other changes to the code that generates the HTML. The
other changes (which are live) include:
AJAX to:
<dfn title="Asynchronous JavaScript and XML">Ajax</a>,
and
<h3><a name='FAQ4_44'>...

<h3 id='FAQ4_44'>...
</h3>


I will raise some of the items as individual discussion topics. Wrapping
everything up on one meta seems a little too much for everyone involved.

Firefox 2 is 2.0.0.17.

?

Garrett

 

[Dr J R Stockton]

What do you mean?

Roughly, I think, compatible with what you meant. Illustrative, rough,
with arbitrary topics :

#.# Topics Better Treated Elsewhere

This group is about JavaScript. For the following topics, the
linked resources are more appropriate :

VBScript <link to ... vbscript>
jQuery <Link to Google Group>
CSS <link to Usenet Stylesheets group>
K9 ? // hope for reader suggestion
Java indicate
Perhaps part of the present Section 2.2 could be done like that, for
efficient compactness. From para 2, only the first sentence is needed.

There's no css for the display of <p>.

But overall font face and size have effect in paragraphs, for example.
I did not write "only within".

We have:

p {
font-size: 100%;
margin-bottom: 0.5em;
margin-left: 2.5em;
margin-top: 0.5em;
}

(inherited values
html {
color: #000000;
font-family: sans-serif;
}

Omit font-family; omit that font-size and anything which causes it to be
useful. I have body font-size: 100%. The indentation of sections is
harmless at worst.

If body has some margin, it can give a little space. Its a little
easier on the eyes.

Yes, text must not abut the window-frame. I use margin: 0; padding:
1ex; but don't recall why I chose padding there. Maybe it is so that
the background fills the window. A pale, but not white, background
allows partly-hidden windows to be more easily recognised.

Where is the 'status of the notes'?

Nowhere. That's a description of an omission.

Do you mean: 5.2 How do I make a suggestion?

No. Section 1 para 5. Search source for "faq_notes" for other
examples.

AFAICS, the Notes themselves have no indication of their authorship,
nothing about their maintenance, nothing about their ownership except
for their URLs - and no dates on the pages. IMHO, they appear to be an
extension of the FAQ, so if you don't indicate otherwise you will he
assumed to be maintaining them.

from ?

Source (as downloaded). But the XML to HTML tool may be responsible.

Changed to :
What should I do before posting to CLJ?

Does the answer seem a little verbose?

As I've said before, FAQ 2.3 needs considerable re-work. It needs to be
friendly but efficient. Splitting it by activity (reading, writing,
asking, replying, announcing) will make it nicer. Some of the rest of 2
could be moved, too.


Somewhere in Section 2, I suggest remarking that, for those who are not
good in English but are fluent in a major Western European language,
bilingual or non-English posts are very acceptable. It seems highly
likely that at least one regular will be able to read each of Spanish
Italian French and German. It's most annoying to be trying to
understand what a Frenchman hopes might be English when he'd be much
more easily understood in good French, possibly aided by Google
Translate. That does not refer to SAM, who is easy enough to
understand.

Those who can only post in less common languages should at least say (in
English) what language they are posting in. Trying various settings in
Google Translate to see which is most plausible gets tedious.

Cyclically? I'll have to get in touch with Bart, then. The changes you
suggested are not live.

You do need to discuss with Bart. But when you rewrite a section, you
can always post it manually for comment.

<h3 id='FAQ4_44'>...

That reminds me : For quickest reference, it seems good to copy the FAQ
to one's local disc, especially for those not sitting in the Company's
broadband. When I save it, the links from index to sections tend to get
changed to be absolute not relative. Then, as soon as I use one, I move
to the remote copy. A few words on how best to save on different
browsers might be of use in the FAQ. Actually, I can save it suitably;
I just cannot recall how!

 

[dhtml]

[snip]

Where is the 'status of the notes'?

Nowhere. That's a description of an omission.

I see.

I do not intend to edit any of the notes unless an author of one of the
articles contacts me with proposed edits. I think I can include that in
the FAQ:

#.# Who maintains the faq notes <URL> ?
<p>
The notes are written by various authors. Look for a <meta
name="author" tag, or on the page for the author details. If it's not
listed, ask on the list.

No. Section 1 para 5. Search source for "faq_notes" for other
examples.

AFAICS, the Notes themselves have no indication of their authorship,
nothing about their maintenance, nothing about their ownership except
for their URLs - and no dates on the pages. IMHO, they appear to be an
extension of the FAQ, so if you don't indicate otherwise you will he
assumed to be maintaining them.

I originally contacted Jim to post an article to the notes and for ideas
about the FAQ. I intend to post an article about form control names soon.

The article I publish will have a meta name="author" in it.

As I've said before, FAQ 2.3 needs considerable re-work. It needs to be
friendly but efficient. Splitting it by activity (reading, writing,
asking, replying, announcing) will make it nicer. Some of the rest of 2
could be moved, too.

I have posted up a revised copy of 2.3.

Somewhere in Section 2, I suggest remarking that, for those who are not
good in English but are fluent in a major Western European language,
bilingual or non-English posts are very acceptable. It seems highly
likely that at least one regular will be able to read each of Spanish
Italian French and German. It's most annoying to be trying to
understand what a Frenchman hopes might be English when he'd be much
more easily understood in good French, possibly aided by Google
Translate. That does not refer to SAM, who is easy enough to
understand.

Those who can only post in less common languages should at least say (in
English) what language they are posting in. Trying various settings in
Google Translate to see which is most plausible gets tedious.

That assumes that the person who is not good in English language is
using Google translate to read the FAQ, can understand the translated
version, and has the patience to ready the (somewhat garbled) machine
translation. That sounds like a very exceptionally careful and serious
person.

You do need to discuss with Bart. But when you rewrite a section, you
can always post it manually for comment.

(changes are live now)
There's something from stopping the mail message from getting through to
Bart:

------------------------------------------------------------
This is an automatically generated Delivery Status Notification

THIS IS A WARNING MESSAGE ONLY.

YOU DO NOT NEED TO RESEND YOUR MESSAGE.

Delivery to the following recipient has been delayed:

bart@[snip].com

Message will be retried for 2 more day(s)

 

[dhtml]

Dr J R Stockton wrote:
In comp.lang.javascript message
<[email protected]>
, Wed, 1 Oct 2008 10:23:36, dhtml <[email protected]> posted:

[snip]

Clarify the status of the Notes. Your FAQ should say whether or not
you
maintain them, and if not then who does.
Where is the 'status of the notes'?

Nowhere. That's a description of an omission.

I see.

I do not intend to edit any of the notes unless an author of one of the
articles contacts me with proposed edits. I think I can include that in
the FAQ:

#.# Who maintains the faq notes <URL> ?
<p>
The notes are written by various authors. Look for a <meta
name="author" tag, or on the page for the author details. If it's not
listed, ask on the list.

No. Section 1 para 5. Search source for "faq_notes" for other
examples.

AFAICS, the Notes themselves have no indication of their authorship,
nothing about their maintenance, nothing about their ownership except
for their URLs - and no dates on the pages. IMHO, they appear to be an
extension of the FAQ, so if you don't indicate otherwise you will he
assumed to be maintaining them.

I originally contacted Jim to post an article to the notes and for ideas
about the FAQ. I intend to post an article about form control names soon.

The article I publish will have a meta name="author" in it.

As I've said before, FAQ 2.3 needs considerable re-work. It needs to be
friendly but efficient. Splitting it by activity (reading, writing,
asking, replying, announcing) will make it nicer. Some of the rest of 2
could be moved, too.

I have posted up a revised copy of 2.3.

Somewhere in Section 2, I suggest remarking that, for those who are not
good in English but are fluent in a major Western European language,
bilingual or non-English posts are very acceptable. It seems highly
likely that at least one regular will be able to read each of Spanish
Italian French and German. It's most annoying to be trying to
understand what a Frenchman hopes might be English when he'd be much
more easily understood in good French, possibly aided by Google
Translate. That does not refer to SAM, who is easy enough to
understand.

Those who can only post in less common languages should at least say (in
English) what language they are posting in. Trying various settings in
Google Translate to see which is most plausible gets tedious.

That assumes that the person who is not good in English language is
using Google translate to read the FAQ, can understand the translated
version, and has the patience to ready the (somewhat garbled) machine
translation. That sounds like a very exceptionally careful and serious
person.

You do need to discuss with Bart. But when you rewrite a section, you
can always post it manually for comment.

(changes are live now)
There's something from stopping the mail message from getting through to
Bart:

------------------------------------------------------------
This is an automatically generated Delivery Status Notification

THIS IS A WARNING MESSAGE ONLY.

YOU DO NOT NEED TO RESEND YOUR MESSAGE.

Delivery to the following recipient has been delayed:

bart@[snip].com

Message will be retried for 2 more day(s)