Re: FAQ Clean-Up

In comp.lang.javascript message <gc3cdq$mb3$1@xxxxxxxxxxxxxxxxxxxxxxxxx>
, Thu, 2 Oct 2008 13:55:09, dhtml <dhtmlkitchen@xxxxxxxxx> posted:
Dr J R Stockton wrote:
In comp.lang.javascript message <gc0bna$qqh$1@xxxxxxxxxxxxxxxxxxxxxxxxx>
, Wed, 1 Oct 2008 10:23:36, dhtml <dhtmlkitchen@xxxxxxxxx> posted:

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


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.zip> Timo Salmi's Turbo Pascal FAQ.
.