FAQ Updates

[Peter Michaux]

The only way the newsgroup FAQ can continue to be updated and stay relevant
is to use a wiki interface with a set of approved editors, so that changes
can be made in real time by a variety of people. It's nearly 2007. It's time
for the FAQ process to catch up with the rest of the web.

I absolutely agree with this idea. I think that a wiki with an approved
set of users would be the best way to go. And below each wiki page a
comment form so that unregistared users can contribute. If their
comments are assimulated into the wiki portion then delete their
comment to keep things clean. I think this is similar to what they call
"biki" format and is like the popular PHP or MySQL documentation
format. I think having a hierachy to the wiki like a table of contents
or book organization would be good to which is again like the PHP and
MySQL docs. And a form so that unregistared users can propose a new
article for review. I have written an app in Rails that is similar to
this but doesn't have the automatic wiki links.

Any other interest in this type of format?

Peter

 

[VK]

I recommend a FAQ entry and a form-letter group reply to VK postings that
contain errors.

I agree on that: but only paired with FAQ of links people saying thank
you to VK: and if they are all as one ignorance followed harmful
advises from me, then it has to be stated near of each link. Btw you
are "cluttering" (by your own expression) c.l.j. a few years longer
then I do but your count on this matter is much lower. Anyway if you
have guts for that second FAQ (with calling stupid everyone who ever
said thank you to me) then just go ahead with the first one. Otherwise
your idee fix with some "contre-VK" posts is getting too boring to read
(means I don't want to see this crap anymore on c.l.j.)

He did not abandon his responsibility. Richard Cornford spent *several
months* of doing FAQ ver 8.x and it became not just FAQ: it became
*his* FAQ, *his* idea of JavaScript, *his* idea of proper and wrong.
And the next maintainer will be the same sooner or later. That is what
some people refuses to understand and this is why I am insisting on
some formal procedure of placing requests and taking actions on these
requests: equally protective for FAQ consistency and for new demands.

The only way the newsgroup FAQ can continue to be updated and stay relevant
is to use a wiki interface with a set of approved editors, so that changes
can be made in real time by a variety of people. It's nearly 2007. It's time
for the FAQ process to catch up with the rest of the web.

And who will these "approved editors" will be? By taking just few
possible candidatures (so sorry of missing others):

Martin Honnen
Richard Cornford
Matt Kruse
Randy Webb
Dr. Stockton
RobG

You mean these people will sit on an article and in some period of time
(lesser than an average human life) they will come to some mutual
"YES"? You must be kidding me! From my four years observations at least
three of them will not agree even on the name of the capital of France,
no matter how many time and posts will be spent. There must be a
defined list of people allowed to say yes or no, but a strict procedure
has to be imposed on the discussion period and on the voting period.

 

[Matt Kruse]

I agree on that: but only paired with FAQ of links people saying thank
you to VK: and if they are all as one ignorance followed harmful
advises from me, then it has to be stated near of each link. Btw you
are "cluttering" (by your own expression) c.l.j. a few years longer
then I do but your count on this matter is much lower.

The fact is, you post a lot to the group and your answers are often
incorrect, or at least lacking insight and experience. You may object to
following "best practices" or thinking things through to a depth that
someone like Richard does, but it's not done just for amusement - there is
real benefit to having a deeper understanding of what you're doing (although
sometimes I find myself wondering if Richard _does_ write such long posts
just for his own amusement . People who read your answers which may work
for them right now in one browser version and on a specific page may be
baffled when it breaks in a different situation. Your "good enough" answers
may do harm in the future.

You should always be open to criticism and self-improvement. I know that I
write things that aren't done in the most optimal way or that can be more
robust, and I like valid criticism that helps me improve.

He did not abandon his responsibility. Richard Cornford spent *several
months* of doing FAQ ver 8.x and it became not just FAQ: it became
*his* FAQ, *his* idea of JavaScript, *his* idea of proper and wrong.

"Facts" are no more than a concensus of beliefs. Any conclusion or Truth is
only as good as your trust in the author who wrote it. If you don't trust
Richard's opinions, then don't read or recommend the document. I wrote my
"Best Practices" document in an attempt to help people, but it isn't perfect
and is subject to *my* ideas (with the input of others).

And the next maintainer will be the same sooner or later. That is what
some people refuses to understand and this is why I am insisting on
some formal procedure of placing requests and taking actions on these
requests: equally protective for FAQ consistency and for new demands.

Formalizing the process merely slows it down. The whole point of a wiki is
to NOT formalize the process, and instead trust in the evolution of
information as it approaches correctness. It's one approach, at least.

And who will these "approved editors" will be? By taking just few
possible candidatures (so sorry of missing others):
Martin Honnen
Richard Cornford
Matt Kruse
Randy Webb
Dr. Stockton
RobG

Looks decent, but I would remove myself (I wouldn't plan to make any
updates) and add Jim Ley, Lasse Nielsen, Michael Winter, and Grant Wagner.

You mean these people will sit on an article and in some period of
time (lesser than an average human life) they will come to some mutual
"YES"? You must be kidding me! From my four years observations at
least three of them will not agree even on the name of the capital of
France, no matter how many time and posts will be spent.

The battle of ideas and debate needed to reach a concenses often ensures the
quality of the resulting document. Although it may be slower to reach a
result, the end result of a concensus of experts is surely of higher quality
and more trustworthy than the same information written by individuals. So
both must exist. Writings by individuals are useful because they are
released rapidly and stay current (such as on peoples' personal sites),
while the FAQ document is slower to evolve and may lag behind the times a
bit but is more robust and peer reviewed, so may be of higher final quality.

 

[VK]

VK wrote:

You mean these people will sit on an article and in some period of time
(lesser than an average human life) they will come to some mutual
"YES"? You must be kidding me! From my four years observations at least
three of them will not agree even on the name of the capital of France,
no matter how many time and posts will be spent. There must be a
defined list of people allowed to say yes or no, but a strict procedure
has to be imposed on the discussion period and on the voting period.

If any doubts left:
<http://groups.google.com/group/comp..._frm/thread/194ae241e7eb3fe6/9d3766211bcca248>

The discussions like that over FAQ topics existing *for many years* I
see four years in the row: with not a single line changed. The linked
one either: after a few of more posts it will go too pathetic and OT so
one remembers anymore what was the practical point of the discussion.

Until everyone's ass is jammed into a strict reglament: 1) discussion
period 2) voting period 3) voting count 4) unconditional update by
majority YES; unconditional decline by majority NO : until that this
body will be as useless as it is now for FAQ updates.

 

[Dr J R Stockton]

Spending time editing a document that is often referred to but apparently
seldom read by the people who could benefit most from it is difficult to
justify.

While it would be better if questioners (and answerers) were to read the
FAQ first, that is not the only way in which it can be useful.

Those who have read the FAQ and are basically in agreement with all of
it (ignoring Section 5) can use a reference to it to give a rapid brief
answer such as "See FAQ 4.17" + URL to common questions. That saves
their time, and also saves the time of the rest of us - when I read such
an answer I know (a) that it is sound, (b) that I'll learn nothing from
the response, and can move to the next article; I need only consider
whether an adequate answer for the given question has been selected.

But when a detailed response is posted in News, whoever by, it does need
to be looked over for accidental slips and omissions; and it does also
need to be looked over by me to see if it contains anything of interest
that I don't already know about. For common questions, the latter has
become rare.

The only way the newsgroup FAQ can continue to be updated and stay relevant
is to use a wiki interface with a set of approved editors, so that changes
can be made in real time by a variety of people. It's nearly 2007. It's time
for the FAQ process to catch up with the rest of the web.

Remember how, with proper software, the newsgroups mechanism can be much
better than straight Web use for those with dial-up or other
intermittent links. Those who sit 24/7 at a broadband link do not need
to use newsgroups but can use web-based forums instead. But even those
who normally use broadband may need from time to time to use dial-up or
similar - I've heard, for instance, that broadband is not everywhere
practical for private use in rural (!=outback) Australia.

 

[Randy Webb]

VK said the following on 11/19/2006 2:23 PM:

Matt Kruse wrote:


He did not abandon his responsibility.

Actually, he did. For whatever reason (that I don't think really
matters) but it isn't being updated and hasn't for a long time. That was
the sole purpose of me starting this thread.

Richard Cornford spent *several months* of doing FAQ ver 8.x and it became
not just FAQ: it became *his* FAQ, *his* idea of JavaScript, *his* idea of
proper and wrong.

And sadly enough, that is true and isn't the way it should be.

And the next maintainer will be the same sooner or later.

To date, the only two names mentioned were mine and Bart. One declined,
the other offered to do it so it would be being done for the time being.
I don't like your implication though. There is a lot in the FAQ that I
disagree with but it is there upon a consensus of this group and that's
the way it should be. Not some supreme person making the final decision
but a group decision.

That is what some people refuses to understand and this is why I am
insisting on some formal procedure of placing requests and taking actions
on these requests: equally protective for FAQ consistency and for new demands.

And if you propose an entry on Associative Arrays in JS and 99% of the
people here say no, what is to stop you from posting it once a week?
That is a two way street.

There must be a defined list of people allowed to say yes or no, but a
strict procedure has to be imposed on the discussion period and on the
voting period.

Your "defined list" suffers the same problem as the list itself. Who is
to create that list and how?

 

[Peter Michaux]

To date, the only two names mentioned were mine and Bart. One declined,
the other offered to do it so it would be being done for the time being.

What do you think of Matt's idea for a wiki format where several people
have a key? Jim Ley's vague criteria of any "known" person without bad
search results having access could be used. That's not me clearly. Just
a suggestion. And with a wiki format server access is not necessary for
small changes.

Peter

 

[Randy Webb]

Dr J R Stockton said the following on 11/19/2006 8:35 AM:

The Editor has plenty of time available. He need only stop arguing with
VK, which is a task that others could undertake more compactly, and then
he would have ample time to edit a FAQ maintained as a simple document.
Instead, he has chosen to abandon the responsibility which he has
undertaken.

Very very true.

I understand that the FAQ is maintained in a more complex form, and
believe that that should not cause significant maintenance overhead. If
it does so cause thereby preventing maintenance, the FAQ source should
change to a simpler form, either plain text or ordinary Web-ready HTML.

I have never understood why it is done the way it is other than
simplicity of producing the Web version and the plain text version for
posting to the group.

It has been brought up before about changing the way it is laid out with
respect to the numbers. It shouldn't be that hard to re-organize it and
have a server script that when a numbered anchor is requested it
redirects to a worded anchor. Then the numbered anchors in the archive
stay "working" but all new references would be #wordRef.

 

[Randy Webb]

Peter Michaux said the following on 11/19/2006 7:24 PM:

What do you think of Matt's idea for a wiki format where several people
have a key?

I have always thought it was a good idea. It was discussed briefly and
Jim agreed to install the wiki software and potentially change the url
to the FAQ to jsfaq.jibbering.com or something similar.

<URL:
http://groups-beta.google.com/group...q=FAQ+Wiki+Randy+Webb&rnum=1#849989733392824e>
<URL:
http://groups-beta.google.com/group...c5fc410b483fe4e?q=FAQ+Wiki+Randy+Webb&lnk=ol&>

Are two threads where it was discussed previously about being a wiki.

Jim Ley's vague criteria of any "known" person without bad search
results having access could be used. That's not me clearly.

I can only think of one person who posts to this group that can be
searched and nothing "bad" found unless someone can find something
bad/wrong that Martin Honnen has ever written here. Martin reminds me of
the old EFHutton commercial "My broker is EFHutton and he says...<dead
silence in the room>".

 

[Richard Cornford]

I agree on that: but only paired with FAQ of links people
saying thank you to VK:

People saying 'thank you' is not much of a criterion to judge anything
by. In a subject where the best answer that can be given is that
addressing a problem with client-side scripting can only be, at best, a
Band-Aid 'hack' and that the real solution lies in some other aspect of
web environment (possibly unknown to the person asking the question), an
individual presenting that answer is unlikely to be thanked for it.
While someone posting the Band-Aid 'hack' along side the best answer may
well be thanked.

There was an ideal example of that earlier in the week when Martin
Honnen asked a question in response to an OP, which, if perused, would
have lead the questioner to the best solution to their problem and a
much better understanding of their web development task, and you later
posted the quick hack that plasters over the real issue. You were the
one that received the thanks, but what you actually did was directly
harm the OP, but leaving them in a position where they may never find
out that you have done so.

After all, nobody has ever disputed that Martine Honnen has more
technical knowledge and more practical experience than anyone else
currently regularly posting to the group (by a factor of at lest two).
In the event that your thought processes in response to a question
differ from Martin's there is absolutely no question that your response
will be significantly inferior. (Indeed, if you had stood back an let
Martin's response pan out to its conclusion you may have learnt enough
not be have embarrassed yourself by displaying such an ignorance of
UTF-8 later in the week)

It really is not very difficult to impress people who don't know any
better (after all, you assert that you are employed in web development
related field, so we have to assume that your employers don't know any
better, and you have no technically knowledgeable colleges, else you
would be out on your ear in no time). Impress people who do understand
the subject and you would have done something telling.

Richard.

 

[Richard Cornford]

Dr J R Stockton wrote:

He need only stop arguing with VK, which is a task that
others could undertake more compactly, and then he
would have ample time to edit a FAQ maintained as a
simple document.

<snip>

Will they? In the thread with the subject "objects with string indices"
these "others" have had two days to point out that when VK states "
15.10.2.11 DecimalEscape is the only place vaguely mentioning \0 and NUL
.... " (in reference to ECMA 262, 3rd ed.) he is a fool to be looking in
the section of the specification that relates to regular expression
literal syntax for information on string literal syntax, or that the
other reference in the spec (making neither the "only place vaguely
mentioning \0"), and the applicable reference in the context of the
thread, is in section 7.8.3.

VK would benefit considerably from more people pointing out his errors
and nonsense because as it is he dismisses the criticism he has received
as personally motivated, regardless of its largely technical nature.

I understand that the FAQ is maintained in a more complex
form, and believe that that should not cause significant
maintenance overhead. If it does so cause thereby preventing
maintenance, the FAQ source should change to a simpler form,
either plain text or ordinary Web-ready HTML.

Bart Van der Donck's unwillingness to discuss the requirements for
modifying the XML format implied in a number of requests for
presentation changes prior to adopting the existing XML format has
potentially had the undesirable side effect of fixing the current
format, as the changes necessary to accommodate the requests for change
will break his server scripts.

Richard.

 

[Richard Cornford]

I absolutely agree with this idea. I think that a wiki with
an approved set of users would be the best way to go.

<snip>

Consider what you have done in the last week in an effort to
'contribute' to the FAQ. You have objected to the use of the word
"equivalent" in the entry about bracket notation, but you proposed no
alternative wording to go in its place. And you have proposed replacing
piece of code in the notes that is intended to demonstrate aspects of
feature detection with another that essentially uses the same tests, but
while the original is commented on every line, so any reader is in now
doubt about what the code is doing and how it is going to work, your
version was code only, leaving it to someone else to turn it into
something that a novice (or inexperienced) reader is likely to
understand well enough to learn from.

This is the norm. It is quite easy for someone to propose some addition
or minor alteration to the FAQ and leave it at that. That is not so
surprising as writing concise, technically accurate and useful
statements that can stand as full answers to specific questions is not
actually easy, and takes quite a bit of practice. After all, look at the
group; what proportion of answers given attempt to explain the whats and
whys, rather than just presenting a "try this" chunk of code?

The FAQ has stated for some time now that anyone could propose an
article for inclusion in the FAQ notes on any relevant subject. The
total number of article proposed for such inclusion to date has been
two; One by an individual who was indirectly promoting an inappropriate
use of the - eval - function, and who got offended at the suggestion
that such code should be removed, and the other from VK, where the
elimination of the technically false statements, confused descriptions,
the irrelevant associations and senseless 'sentences' would not have
left more than half a paragraph.

From this starting point do you really think that some nominated group
of regular contributors to this group are going to start creating
content that they have been unwilling to create to date? That the FAQ
being a wiki will somehow give them more time or more inclination?

I assume you are proposing "an approved set of users" because you have
perceived the consequences of letting anyone at all participate; that
the time and effort required to remove the 'contributions' of
individuals like VK who perceive their best interests in promoting the
lowest possible technical standard in web development would likely
overwhelm the minority who know the subject. Leave a result that was at
least partly technically wrong most of the time and would eventually
degenerate into an object that was worthless as a source of information.
But now you have excluded the possibility that someone may come along
who does know the subject, or (even worse) that someone may come along
with a very specific specialised interest in one aspect of javascript or
browser scripting. such an individual might contribute a very valuable
article to the notes, but they are not going to get the keys to your
wiki for some time.

There is little point in discussing alternative ways of creating a FAQ
until you can find people who are both willing and able to create the
content for it.

Richard.

 

[Peter Michaux]

Peter Michaux said the following on 11/19/2006 7:24 PM:

I have always thought it was a good idea. It was discussed briefly and
Jim agreed to install the wiki software

Sounds like it's almost settled. A wiki would be a great format to
aggregate knowledge in a more organized way then the newsgroup
archives. I don't know how you would generate a faq out of it but maybe
faq's are a little dated now anyway if good search results are
available. And like Matt says it's more important to be able to cite
the knowledge then to post it to the newsgroup as it probably goes
largely ignored.

Like I said before, I think it would be very good if non-registared
users were able to post comments on wiki pages so that anyone could
feel involved. This is the kind of JavaScript site I really wished
existed. The experienced members of this group are the only truely
knowledgable source of detailed JavaScript knowledge I've encountered
and having an easy way to organize this knowledge interactively would
be impressive.

How much bandwidth does the jibbering faq site use monthly?

and potentially change the url
to the FAQ to jsfaq.jibbering.com or something similar.

How about

http://seriousjavascript.info

Peter

 

[Jim Ley]

What do you think of Matt's idea for a wiki format where several people
have a key?

I personally think Wiki documentation rarely works - I've seen it
other places (SVG etc.) but people have grand plans, but never get
into enough detail.

Jim Ley's vague criteria of any "known" person without bad
search results having access could be used.

That's just access to the machine! I don't want to let just anyone
access the machine, I'll gladly assist anyone else willing to do it -
it's just if I already "know" them from clj, then I'm going to trust
them.

And with a wiki format server access is not necessary for
small changes.

I would host a wiki certainly.

Cheers,

Jim.

 

[Jim Ley]

I can only think of one person who posts to this group that can be
searched and nothing "bad" found unless someone can find something
bad/wrong that Martin Honnen has ever written here.

Bad in the sense of a reputation of abusing server access not bad
as in making mistakes or getting pissed off people on usenet....

Jim.

 

[Jim Ley]

How much bandwidth does the jibbering faq site use monthly?

The site as a whole does over 20gig, I'm happy to continue hosting it
- I really need to get it on the new hardware though.

Jim.

 

[Bart Van der Donck]

Bart Van der Donck's unwillingness to discuss the requirements for
modifying the XML format implied in a number of requests for
presentation changes prior to adopting the existing XML format has
potentially had the undesirable side effect of fixing the current
format, as the changes necessary to accommodate the requests for change
will break his server scripts.

All I can say is that any content is possible as long as it's in the
following structure:

<FAQ>
<TITLE>title goes here</TITLE>
<CONTENTS>
<CONTENT TITLE="name of chapter 1">
<CONTENT TITLE="question 1">
answer 1
</CONTENT>
<CONTENT TITLE="question 2">
answer 2
</CONTENT>
</CONTENT>
<CONTENT TITLE="name of chapter 2">
<CONTENT TITLE="question 3">
answer 3
</CONTENT>
</CONTENT>
</CONTENTS>
</FAQ>

You're right that this is somewhat restrictive; but a XML parsing
program must know the data structure per definition. I think the
current format should leave enough room for flexible maintenance and
extension. But the group is free to vote otherwise, of course.

Contrary to other posts in this thread, I would tend to use a database
and a maintenance interface. The XML file could then be updated
automatically from DB content.

 

[Dr J R Stockton]

In comp.lang.javascript message

It is quite easy for someone to propose some addition
or minor alteration to the FAQ and leave it at that. That is not so
surprising as writing concise, technically accurate and useful
statements that can stand as full answers to specific questions is not
actually easy, and takes quite a bit of practice.

And that is something that you have completely failed to do for the
newsgroup FAQ, at least to do visibly, over the past year.

Moreover, from what one sees of your writing, mainly to VK, it is
(however technically accurate) not in a style accessible to the sort of
newcomer that FAQs are intended for.

FAQ maintenance should be transferred to some javascript expert who will
be able to actually *produce* suitable material in sound English [*].

Would it be possible, Jim, for you to create a Web forum in which VK,
RC, and that ilk can debate to their hearts' content without polluting
this newsgroup? Would it work?


[*] IMHO, that requires someone who has been taught good English
properly; and that means, nowadays, someone from one of the smaller
countries of Mainland Europe. See sig!

 

[Dr J R Stockton]

In comp.lang.javascript message

Sounds like it's almost settled. A wiki would be a great format to
aggregate knowledge in a more organized way then the newsgroup
archives. I don't know how you would generate a faq out of it but maybe
faq's are a little dated now anyway if good search results are
available. And like Matt says it's more important to be able to cite
the knowledge then to post it to the newsgroup as it probably goes
largely ignored.

I completely disagree. Such a site might be a valuable and accurate
resource, but it would not be a *newsgroup* FAQ.

The essence of a newsgroup FAQ is that the regular readers of the
newsgroup must feel a collective responsibility for it, and exercise
that responsibility through the medium of a co-operative editorial
system. For that, the FAQ *must* be routinely published in the
newsgroup, whether in large lumps or small, and it *must* reflect
ongoing discussion in the newsgroup. It *must* have the continuing
agreement of the current users of the group. There is no *need* for it
to have any more Web presence than that provided by Web/News interfaces.


As for finding material by Web search - it is tautologically inevitable
that half of the Web material is of less than median quality, and it is
easy to see that very much more than half is mediocre. It's also easy
to see that, inevitably, newcomers have the ability neither to formulate
a search biased to good material nor to assess the quality of what they
do find.

If you want to build such a site, go away and do it. It may be a
valuable site; it may be a FAQ about the same topics as but
it will not be a FAQ. Let the FAQ be continued,
as a FAQ, by someone willing and able to actually do it.

 

[Randy Webb]

Jim Ley said the following on 11/20/2006 6:04 AM:

Bad in the sense of a reputation of abusing server access not bad
as in making mistakes or getting pissed off people on usenet....

Whew! Since you rule out making mistakes and pissing people off I might
be alright now