By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
435,608 Members | 3,801 Online
Bytes IT Community
+ Ask a Question
Need help? Post your question and get tips & solutions from a community of 435,608 IT Pros & Developers. It's quick & easy.

FAQ Clean-Up

P: n/a
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
Oct 1 '08 #1
Share this Question
Share on Google+
3 Replies


P: n/a
In comp.lang.javascript message <gc**********@registered.motzarella.org>
, Thu, 2 Oct 2008 13:55:09, dhtml <dh**********@gmail.composted:
>Dr J R Stockton wrote:
>In comp.lang.javascript message <gc**********@registered.motzarella.org>
, Wed, 1 Oct 2008 10:23:36, dhtml <dh**********@gmail.composted:
>>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.

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 news:microsoft ... vbscript>
jQuery <Link to Google Group>
CSS <link to Usenet Stylesheets group>
K9 ? // hope for reader suggestion
Java indicate news:comp.lang.java.*

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.

>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<codefont.

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.

> 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.
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.

>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.
>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.

>Omit trailing whitespace !

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!
--
(c) John Stockton, nr London UK. ?@merlyn.demon.co.uk Turnpike v6.05 MIME.
<URL:http://www.merlyn.demon.co.uk/TP/BP/Delphi/&c., FAQqy topics & links;
<URL:http://www.merlyn.demon.co.uk/clpb-faq.txt RAH Prins : c.l.p.b mFAQ;
<URL:ftp://garbo.uwasa.fi/pc/link/tsfaqp.zipTimo Salmi's Turbo Pascal FAQ.
Oct 3 '08 #2

P: n/a
Dr J R Stockton wrote:
In comp.lang.javascript message <gc**********@registered.motzarella.org>
, Thu, 2 Oct 2008 13:55:09, dhtml <dh**********@gmail.composted:
>Dr J R Stockton wrote:
>>In comp.lang.javascript message <gc**********@registered.motzarella.org>
, Wed, 1 Oct 2008 10:23:36, dhtml <dh**********@gmail.composted:
[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.
>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.

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.

>
>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.
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.
>
>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.

(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)
Oct 4 '08 #3

P: n/a
dhtml wrote:
Dr J R Stockton wrote:
>In comp.lang.javascript message <gc**********@registered.motzarella.org>
, Thu, 2 Oct 2008 13:55:09, dhtml <dh**********@gmail.composted:
>>Dr J R Stockton wrote:
In comp.lang.javascript message
<gc**********@registered.motzarella.org>
, Wed, 1 Oct 2008 10:23:36, dhtml <dh**********@gmail.composted:
[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.
>>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.


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.

>>
>>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.

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.
>>
>>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.


(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)

Oct 4 '08 #4

This discussion thread is closed

Replies have been disabled for this discussion.