Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Javascript > FAQ/FAQ notes site makeover

Reply
Thread Tools

FAQ/FAQ notes site makeover

 
 
Peter Michaux
Guest
Posts: n/a
 
      11-22-2006
Hi,

There have been a few suggestions for changing the format of the FAQ
site to make it easier to maintain. VK suggested and XML procedure.
Matt Kruse suggested a wiki. I think something interactive would be
good. Jim Ley pointed out wiki documentation doesn't always work well.

I think a book type hierarchy of articles with user comments on each
page would be a great way to go as it has been so successful for both
PHP and MySQL. I am willing to write a Rails app to do this if the task
is not too onerous. I put up a simple little demo (not production
ready).

http://seriousjavascript.info

(Try the insert code example)

I think being able to maintain the site without ftp would be nicer. Of
course features could be added over time and anyone could checkout the
Rails app with svn and submit patches.

I am not suggesting I would be one of the JavaScript technical experts
or that Jim Ley would stop hosting the site.

Perhaps it is up to Jim Ley and Randy Webb to make the decision if
there will be a change in the format. I just thought that I'd make the
offer and that the ball might start rolling.

Peter

 
Reply With Quote
 
 
 
 
Randy Webb
Guest
Posts: n/a
 
      11-22-2006
Peter Michaux said the following on 11/21/2006 11:28 PM:
> Hi,
>
> There have been a few suggestions for changing the format of the FAQ
> site to make it easier to maintain. VK suggested and XML procedure.


That suffers a major problem whereby people who don't know XML will feel
left out. To me, there is nothing wrong with the current way of
requesting a modification. It is simple, and available to anyone that
can post to the group.

> Matt Kruse suggested a wiki.


The problem with a wiki is two-fold:

1) If you grant open access (much like wikipedia does), then you have
anybody posting anything and people spending too much time correcting
things.

2) If you limit access to a few people, how do you decide who those
people are going to be? No matter who is on that list you are going to
have people complaining about it. If they are complaining now and going
to complain then, whats the benefit?

> I think something interactive would be good.


The current format, to me, is fine other than getting it updated. I half
agree with Richard in that not many people post even snippets to get put
into the FAQ (Draft Proposals) they just want to say "This should be in
the FAQ" and leave it up to Richard to write it out so that people can
still complain about what it says. I have never written a Notes section,
or even an Entry for the FAQ so I can't claim total innocence with
regards to that part.

> Jim Ley pointed out wiki documentation doesn't always work well.


Yes, and for the above reasons, not the one's JRS likes to use though.

> I think a book type hierarchy of articles with user comments on each
> page would be a great way to go as it has been so successful for both
> PHP and MySQL.


The difference between PHP/MySQL and Javascript FAQ's are substantial
though. One runs on the server where you can dictate the environment and
the other doesn't.

The problem with a "book type heirarchy" though makes it difficult to
put it all in one page. People don't read the single page there is now,
why would they be interested in reading an entire book? Especially if
they have to hunt what they are looking for. A simple Search on the FAQ
page now will find (or reject) whatever you are looking for. What would
be nice for the FAQ though is a Search/Find/Highlight in the page itself
so you don't have to do it manually.

> I am willing to write a Rails app to do this if the task
> is not too onerous. I put up a simple little demo (not production
> ready).
> http://seriousjavascript.info
>
> (Try the insert code example)


The insert code example isn't any good to most people though and not
sure what benefit it would have in a FAQ. What's the point of being able
to dynamically insert code into a FAQ page?

> I think being able to maintain the site without ftp would be nicer. Of
> course features could be added over time and anyone could checkout the
> Rails app with svn and submit patches.
>
> I am not suggesting I would be one of the JavaScript technical experts
> or that Jim Ley would stop hosting the site.
>
> Perhaps it is up to Jim Ley and Randy Webb to make the decision if
> there will be a change in the format. I just thought that I'd make the
> offer and that the ball might start rolling.


Personally, I think for now, the best thing to do is give me a week or
two to go back to the last update and try to get the FAQ now updated
first, then move on to a different format if it is desired. I do think
the anchor issue now needs to be changed to a word anchor instead of
numbers. I still have to get in touch with Jim to get a
username/password to get on the server but have already started hunting
down entry requests.

--
Randy
Chance Favors The Prepared Mind
comp.lang.javascript FAQ - http://jibbering.com/faq
Javascript Best Practices - http://www.JavascriptToolbox.com/bestpractices/
 
Reply With Quote
 
 
 
 
Peter Michaux
Guest
Posts: n/a
 
      11-22-2006
Randy Webb wrote:

> The problem with a wiki is two-fold:
>
> 1) If you grant open access (much like wikipedia does), then you have
> anybody posting anything and people spending too much time correcting
> things.


I don't think anyone here would want to do that much correcting.
Wikipedia already exists for this and if folks know that the c.l.j.
resource is somewhat verified it has a different appeal.


> 2) If you limit access to a few people, how do you decide who those
> people are going to be? No matter who is on that list you are going to
> have people complaining about it. If they are complaining now and going
> to complain then, whats the benefit?


I don't think this is really a big problem. All open source projects
have a subset of contributors with commit status. You could scream for
commit status until you are blue in the face but if the people who hand
out commit status won't give it then you are out of luck. The important
part is having different ways so that everyone can contribute and feel
part of the effort.

> > I think a book type hierarchy of articles with user comments on each
> > page would be a great way to go as it has been so successful for both
> > PHP and MySQL.

>
> The difference between PHP/MySQL and Javascript FAQ's are substantial
> though. One runs on the server where you can dictate the environment and
> the other doesn't.


Is it not possible to dictate the environment on the JavaScript FAQ
server? Jim Ley mentioned he would pass out SSH access to a known
person.


> The problem with a "book type heirarchy" though makes it difficult to
> put it all in one page.


Not at all. That is quite easy actually. Just travel down the book tree
and concat the sections.


> People don't read the single page there is now,


Then the whole exercise is futile

Actually I think this is an important point. Why don't they read it
now? People are searching for JavaScript information all the time.
Perhaps a new format would be more exciting and generate more use of
the FAQ and FAQ notes.


> why would they be interested in reading an entire book?


I meant a book-type organization to the faq page and notes. Not
necessarily 1000 pages of notes.


> Especially if
> they have to hunt what they are looking for. A simple Search on the FAQ
> page now will find (or reject) whatever you are looking for.


If the FAQ itself is a single node in the hierarchy then this would
remain. Or the FAQ sections could be concatenated on the fly to
generate a complete FAQ. There are options.


> What would
> be nice for the FAQ though is a Search/Find/Highlight in the page itself
> so you don't have to do it manually.


That would be a nice feature.


> > I am willing to write a Rails app to do this if the task
> > is not too onerous. I put up a simple little demo (not production
> > ready).
> > http://seriousjavascript.info
> >
> > (Try the insert code example)

>
> The insert code example isn't any good to most people though and not
> sure what benefit it would have in a FAQ. What's the point of being able
> to dynamically insert code into a FAQ page?


I think this insert code example would be good in the notes. After
inserting the code then it is easy to play with the code in the Firefox
Firebug console or another javascript console. I have been using this
trick with my own notes quite a bit lately and it is very useful. It is
nice to interact with the code live sometimes. JavaScript is a uniqe
programming language in that it's examples presented in HTML can be
dynamic like this.


> > I think being able to maintain the site without ftp would be nicer. Of
> > course features could be added over time and anyone could checkout the
> > Rails app with svn and submit patches.
> >
> > I am not suggesting I would be one of the JavaScript technical experts
> > or that Jim Ley would stop hosting the site.
> >
> > Perhaps it is up to Jim Ley and Randy Webb to make the decision if
> > there will be a change in the format. I just thought that I'd make the
> > offer and that the ball might start rolling.

>
> Personally, I think for now, the best thing to do is give me a week or
> two to go back to the last update and try to get the FAQ now updated
> first, then move on to a different format if it is desired.


I was thinking that if a change in format was desired then the two
efforts (content and format) could proceed in parallel.

Peter

 
Reply With Quote
 
Randy Webb
Guest
Posts: n/a
 
      11-22-2006
Peter Michaux said the following on 11/22/2006 12:42 AM:
> Randy Webb wrote:
>
>> The problem with a wiki is two-fold:
>>
>> 1) If you grant open access (much like wikipedia does), then you have
>> anybody posting anything and people spending too much time correcting
>> things.

>
> I don't think anyone here would want to do that much correcting.


Then it would get bloated with incorrect information.

The other problem with a wiki based approach is that if you leave it
open for *any* subject, then it ceases to be an FAQ site and becomes a
documentation site.

> Wikipedia already exists for this and if folks know that the c.l.j.
> resource is somewhat verified it has a different appeal.


I asked twice in the other thread on the FAQ how you would go about
deciding who to grant edit access to and VK didn't answer me either
time. Either you have a wide open format where anybody can post (like
wikipedia does) and you have problems. If you limit access to post, you
have problems. If it is limited access then yes, it is "verified", but
you still have to have some mechanism in place for non editors to
contribute.

>> 2) If you limit access to a few people, how do you decide who those
>> people are going to be? No matter who is on that list you are going to
>> have people complaining about it. If they are complaining now and going
>> to complain then, whats the benefit?

>
> I don't think this is really a big problem. All open source projects
> have a subset of contributors with commit status. You could scream for
> commit status until you are blue in the face but if the people who hand
> out commit status won't give it then you are out of luck. The important
> part is having different ways so that everyone can contribute and feel
> part of the effort.


True, and that part is there now. The faq modification process is very
well established and *anybody* can make a request to have the FAQ
modified so making it a wiki wouldn't change anything in that regards.

>>> I think a book type hierarchy of articles with user comments on each
>>> page would be a great way to go as it has been so successful for both
>>> PHP and MySQL.

>> The difference between PHP/MySQL and Javascript FAQ's are substantial
>> though. One runs on the server where you can dictate the environment and
>> the other doesn't.

>
> Is it not possible to dictate the environment on the JavaScript FAQ
> server? Jim Ley mentioned he would pass out SSH access to a known
> person.


I wasn't referring to Jim's server. I was referring to the environment
that PHP and mySQL execute in. Trying to find a needle in the haystack
in PHP is simple, but trying to dynamically load a .js file and execute
it in a browser is totally different. You can't quite document JS with
simple answers was my only point.

>> The problem with a "book type heirarchy" though makes it difficult to
>> put it all in one page.

>
> Not at all. That is quite easy actually. Just travel down the book tree
> and concat the sections.


A Javascript FAQ isn't that large though. Its about Frequently Asked
Questions and it changes over time. There are some FAQ's now that
weren't even heard of 3 years ago (witness: AJAX) but there are some
that get asked forever and ever (witness: eval). The problem with that
is historical reasons. You can't delete entries because it will kill 99%
of the links in the archives. So, it just keeps growing and growing

>> People don't read the single page there is now,

>
> Then the whole exercise is futile


Probably so.

> Actually I think this is an important point. Why don't they read it
> now? People are searching for JavaScript information all the time.


#1 Reason? Improper search term. A Google search for "Javascript FAQ"
turns up this groups FAQ as the #3 hit.

The second reason is the ease with which people can post a question in
Usenet now. Before Google Groups, you had to go through the steps of
setting up a newsreader, opening a Usenet account, subscribing, etc..
Now, you can post to Google Groups in under 10 minutes. Email address is
all that is required and Google will even give you that (GMail). It's
"easier" to just ask the question than to try to find the answer. Why
search through the archives hunting an answer when you can post in less
time than that?

Probably half of the questions asked here are of the type "I am not a JS
programmer, just need a little help". They don't want to learn JS, they
just want free programming.

> Perhaps a new format would be more exciting and generate more use of
> the FAQ and FAQ notes.


Only to the people interested in actually learning instead of just
wanting an answer so they can move on.

>> why would they be interested in reading an entire book?

>
> I meant a book-type organization to the faq page and notes. Not
> necessarily 1000 pages of notes.


I was thinking more of a book type where each "chapter" would be a
different page with a table of contents. I still don't think it would
add anything to what is there now as most of the answers are "Quick
Answers". I do think that if there was a Notes page linked to from each
entry in Section 4 then it would eventually turn into a Book format
though. You get a Quick Answer and a link to the Chapter that explains
it in more detail.

>> Especially if
>> they have to hunt what they are looking for. A simple Search on the FAQ
>> page now will find (or reject) whatever you are looking for.

>
> If the FAQ itself is a single node in the hierarchy then this would
> remain. Or the FAQ sections could be concatenated on the fly to
> generate a complete FAQ. There are options.


True.

>> What would
>> be nice for the FAQ though is a Search/Find/Highlight in the page itself
>> so you don't have to do it manually.

>
> That would be a nice feature.





>>> I am willing to write a Rails app to do this if the task
>>> is not too onerous. I put up a simple little demo (not production
>>> ready).
>>> http://seriousjavascript.info
>>>
>>> (Try the insert code example)

>> The insert code example isn't any good to most people though and not
>> sure what benefit it would have in a FAQ. What's the point of being able
>> to dynamically insert code into a FAQ page?

>
> I think this insert code example would be good in the notes. After
> inserting the code then it is easy to play with the code in the Firefox
> Firebug console or another javascript console. I have been using this
> trick with my own notes quite a bit lately and it is very useful. It is
> nice to interact with the code live sometimes. JavaScript is a uniqe
> programming language in that it's examples presented in HTML can be
> dynamic like this.


I have become so adept at <ALT><ENTER><DOWN><DOWN><ENTER><ALT-TAB><F5>
with a test page that I just personally don't see a benefit for me.
Especially when I can make a test page to save locally and always have
my code handy to tinker with and test in different browsers.

>>> I think being able to maintain the site without ftp would be nicer. Of
>>> course features could be added over time and anyone could checkout the
>>> Rails app with svn and submit patches.
>>>
>>> I am not suggesting I would be one of the JavaScript technical experts
>>> or that Jim Ley would stop hosting the site.
>>>
>>> Perhaps it is up to Jim Ley and Randy Webb to make the decision if
>>> there will be a change in the format. I just thought that I'd make the
>>> offer and that the ball might start rolling.

>> Personally, I think for now, the best thing to do is give me a week or
>> two to go back to the last update and try to get the FAQ now updated
>> first, then move on to a different format if it is desired.

>
> I was thinking that if a change in format was desired then the two
> efforts (content and format) could proceed in parallel.


I sat tonight and hunted down the Entry requests since the last update
was done. I am positive I missed some because of the recent faq postings
that got discussed. So far, I have 44 requested entries to go through,
try to write/modify the entries, post it to the group, remodiy/edit, and
then get it posted. The last thing I want to do in the middle of all
that is deal with a new format. Get the FAQ now updated, get it posted
regularly again, and then come back to the format issue.

--
Randy
Chance Favors The Prepared Mind
comp.lang.javascript FAQ - http://jibbering.com/faq
Javascript Best Practices - http://www.JavascriptToolbox.com/bestpractices/
 
Reply With Quote
 
VK
Guest
Posts: n/a
 
      11-22-2006
Peter Michaux said the following on 11/21/2006 11:28 PM:
> > There have been a few suggestions for changing the format of the FAQ
> > site to make it easier to maintain. VK suggested and XML procedure.


Randy Webb wrote:
> That suffers a major problem whereby people who don't know XML will feel
> left out. To me, there is nothing wrong with the current way of
> requesting a modification. It is simple, and available to anyone that
> can post to the group.


That is not what I said. I proposed to submit the requests for updates
in XML format in the body of Usenet post , while the discussion over
the request is conducted in the regular free form:
<http://groups.google.com/group/comp.lang.javascript/msg/38f5dc6bf2599884>

Each FAQ topic is a properly formatted HTML thus well-formed XML
fragment anyway. But to make the process even more user-friendly it is
easy to add a script-driven request generator with each topic having
"Generate update request" button.

The discussion itself will be conducted in c.l.j. itself in the regular
form of Usenet thread; some web-based wiki interfaces on some side
website are great by themselves but irrelevant to the Usenet.

The side effect is that FAQ will not stay on the "bleeding edge" of the
JavaScript/DOM programming technologies. The other side effect is that
possibly that FAQ topics will not accomodate all and every accumulated
world wisdom on the subject. These side effects are easy to live with
because from the other side it will protect the topics from crap and
IE-only techniques.

As Rendy Webb seems to be the next maintainer (?) the question remains
about the list of people allowed to vote.

VK list:
> 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


Matt Kruse list:
> 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.


 
Reply With Quote
 
VK
Guest
Posts: n/a
 
      11-22-2006
P.S. What was the need to break the original "FAQ Updates" thread and
to start a new one? That makes reading and referencing more difficult.
IMHO "FAQ Updates" topic covers well all issues of the discussion.

 
Reply With Quote
 
John G Harris
Guest
Posts: n/a
 
      11-22-2006
In article <(E-Mail Removed). com>, Peter
Michaux <(E-Mail Removed)> writes
>Hi,
>
>There have been a few suggestions for changing the format of the FAQ
>site to make it easier to maintain. VK suggested and XML procedure.
>Matt Kruse suggested a wiki. I think something interactive would be
>good. Jim Ley pointed out wiki documentation doesn't always work well.
>
>I think a book type hierarchy of articles with user comments on each
>page would be a great way to go as it has been so successful for both
>PHP and MySQL. I am willing to write a Rails app to do this if the task
>is not too onerous. I put up a simple little demo (not production
>ready).

<snip>

Spreading the FAQ document over more than one web page is a disaster ...

a) for those using dialup access paid by the minute who want to read the
web page offline;

b) for those using a laptop wanting to read the web page away from a
phone socket or a secure WiFi transceiver, and hence want to read it
offline.

The FAQ document needs to be simple enough to be posted to
comp.lang.javascript. This pretty well forces it to be capable of being
(re)formatted as a single text document.

People thinking of posting a 'newbie' question to comp.lang.javascript
are encouraged to read the FAQ document first. The document must
therefore be one that can be skimmed through quickly by people who don't
know what it is they don't know about the language.

A wiki may well be suitable for a good practice and handy hints
textbook, but even then it must have a guaranteed up-to-date contents
list. It's no use relying on people guessing the right search terms to
use.

John
--
John Harris
 
Reply With Quote
 
Randy Webb
Guest
Posts: n/a
 
      11-22-2006
VK said the following on 11/22/2006 5:44 AM:
> Peter Michaux said the following on 11/21/2006 11:28 PM:
>>> There have been a few suggestions for changing the format of the FAQ
>>> site to make it easier to maintain. VK suggested and XML procedure.

>
> Randy Webb wrote:
>> That suffers a major problem whereby people who don't know XML will feel
>> left out. To me, there is nothing wrong with the current way of
>> requesting a modification. It is simple, and available to anyone that
>> can post to the group.

>
> That is not what I said. I proposed to submit the requests for updates
> in XML format in the body of Usenet post ,


And I responded to that, which you quoted, by saying that it suffers
from people now knowing XML to post it to the group. And as I said,
there is nothing wrong with the way the requests are made now. The
problem is updating the FAQ with the requested changes.

> while the discussion over the request is conducted in the regular free form:
> <http://groups.google.com/group/comp.lang.javascript/msg/38f5dc6bf2599884>
>
> Each FAQ topic is a properly formatted HTML thus well-formed XML
> fragment anyway. But to make the process even more user-friendly it is
> easy to add a script-driven request generator with each topic having
> "Generate update request" button.


So to make a request they have to go to the FAQ, create a request,
copy/paste that request to Usenet and post it to the group? I bet JRS
loves that idea.

> The discussion itself will be conducted in c.l.j. itself in the regular
> form of Usenet thread; some web-based wiki interfaces on some side
> website are great by themselves but irrelevant to the Usenet.


There has never been a question of where it would be "discussed". It
always has been, and always will be, discussed in the group.

> The side effect is that FAQ will not stay on the "bleeding edge" of the
> JavaScript/DOM programming technologies. The other side effect is that
> possibly that FAQ topics will not accomodate all and every accumulated
> world wisdom on the subject. These side effects are easy to live with
> because from the other side it will protect the topics from crap and
> IE-only techniques.


Both are "side effects" but neither are negative side effects.

> As Rendy Webb seems to be the next maintainer (?) the question remains
> about the list of people allowed to vote.


And I have asked three times, twice directly of you, how you would
propose to create that list of people "allowed to vote". And, to date,
you have not answered that.

--
Randy
Chance Favors The Prepared Mind
comp.lang.javascript FAQ - http://jibbering.com/faq
Javascript Best Practices - http://www.JavascriptToolbox.com/bestpractices/
 
Reply With Quote
 
Randy Webb
Guest
Posts: n/a
 
      11-22-2006
Joe D Williams said the following on 11/22/2006 12:13 PM:
>>>> ... suggested a wiki.

>
> There already is wiki:
> http://en.wikipedia.org/wiki/JavaScript
> http://en.wikipedia.org/wiki/ECMAScript
>
> a goal could be to get the 'official' c.l.j. faq mentioned
> or even actually referenced from those entries.


It is now listed on the main page for the JavaScript entry at the bottom
in the external links section.

--
Randy
Chance Favors The Prepared Mind
comp.lang.javascript FAQ - http://jibbering.com/faq
Javascript Best Practices - http://www.JavascriptToolbox.com/bestpractices/
 
Reply With Quote
 
Dr J R Stockton
Guest
Posts: n/a
 
      11-22-2006
In comp.lang.javascript message <(E-Mail Removed)>,
Wed, 22 Nov 2006 00:17:25, Randy Webb <(E-Mail Removed)> wrote:
>
>The current format, to me, is fine other than getting it updated. I
>half agree with Richard in that not many people post even snippets to
>get put into the FAQ (Draft Proposals) they just want to say "This
>should be in the FAQ" and leave it up to Richard to write it out so
>that people can still complain about what it says. I have never written
>a Notes section, or even an Entry for the FAQ so I can't claim total
>innocence with regards to that part.


For the last several months, at least, it has been clear that Richard
was not doing the job that he had undertaken, preferring to waste effort
and news-space in arguing with VK (Others can do that; and VK's
inabilities are evident enough anyway).


People have posted suggestions to get the suggestions "on the record",
or as a sideline when responding to an actual question.. In some cases
a competent and active FAQ maintainer would have no difficulty in making
the corresponding change, or an adequate first approximation thereto,
immediately. In other cases a maintainer should either post a draft, or
a request for a draft, or a tactful criticism of the idea, without delay
in News. He should neither ignore it nor give the appearance of
ignoring it.

--
(c) John Stockton, Surrey, UK. REPLYyyww merlyn demon co uk Turnpike 6.05.
Web <URL:http://www.uwasa.fi/~ts/http/tsfaq.html> -> Timo Salmi: Usenet Q&A.
Web <URL:http://www.merlyn.demon.co.uk/news-use.htm> : about usage of News.
No Encoding. Quotes precede replies. Snip well. Write clearly. Mail no News.
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
C# 2.0 (Lotus Notes 6 & 7) Create mail document in draft folder for Lotus Notes SteveM ASP .Net 5 08-28-2007 04:16 PM
Accessing email from Notes-mail-server without Lotus Notes installed Bjorn Jensen Perl 0 03-22-2005 01:44 PM
DVD Verdict reviews: EXTREME MAKEOVER FITNESS: WEIGHT LOSS WORKOUT FOR BEGINNERS and more! DVD Verdict DVD Video 0 02-24-2005 09:11 AM
Oracle to finish Linux makeover this year TechNews Computer Support 2 05-27-2004 08:48 PM
pc makeover??? longshotjohn7 Computer Support 0 08-28-2003 04:09 AM



Advertisments