FAQ/FAQ notes site makeover

Discussion in 'Javascript' started by Peter Michaux, Nov 22, 2006.

  1. 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
    Peter Michaux, Nov 22, 2006
    #1
    1. Advertising

  2. Peter Michaux

    Randy Webb Guest

    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/
    Randy Webb, Nov 22, 2006
    #2
    1. Advertising

  3. 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
    Peter Michaux, Nov 22, 2006
    #3
  4. Peter Michaux

    Randy Webb Guest

    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/
    Randy Webb, Nov 22, 2006
    #4
  5. Peter Michaux

    VK Guest

    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.
    VK, Nov 22, 2006
    #5
  6. Peter Michaux

    VK Guest

    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.
    VK, Nov 22, 2006
    #6
  7. In article <>, Peter
    Michaux <> 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
    John G Harris, Nov 22, 2006
    #7
  8. Peter Michaux

    Randy Webb Guest

    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/
    Randy Webb, Nov 22, 2006
    #8
  9. Peter Michaux

    Randy Webb Guest

    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/
    Randy Webb, Nov 22, 2006
    #9
  10. In comp.lang.javascript message <>,
    Wed, 22 Nov 2006 00:17:25, Randy Webb <> 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.
    Dr J R Stockton, Nov 22, 2006
    #10
  11. Peter Michaux

    VK Guest

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


    Right: and if the Initial Request and Call For Votes (CFV) (if
    followed) are both made as well-formed XML fragment then the
    maintainer's task is as simple as copy-n-paste the final variant into
    the relevant section (if voted YES).
    No one is asking from requestors to develop a full-scaled validating
    XML document with prolog, matching DTD etc. The task is as simple as to
    put properly a couple of tags and to use properly <del> and <ins> tags
    (if request for update). If it constitutes too much of challenge for
    some person, then most probably this person did not reach yet the level
    to request any updates, she is still on the stage to *read* FAQ and ask
    questions if something is not clear.

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


    Yes, before to request to change something, they have to read that
    something in full and possibly in the context of surrounding topics.
    They have to demonstrate an ability to navigate across the Web (at
    least in the most primitive form), be able to hit the right button (at
    least from the 3rd attempt) and be interested in improving group FAQ
    (at least up to the level to spend extra 30sec for it). I see nothing
    wrong in some most primitive medical and moral testing :) of a person
    before a bunch of people will start discussing the request.

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


    Great to have it confirmed.

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


    This is what I meant.

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


    I did better :) I started the list and I have shown how to possibly
    make it. I posted the initial list, Matt Kruse asked to take him off
    but added few more people. You may now add/remove your own names. The
    others in the list is welcome to do the same. I personally do not like
    too much the idea of "voters by honor": thus people who did not post at
    c.l.j. for many years already yet included because they were great
    posters 4,5,6 years ago. IMO that should be a practically usable list,
    not a historical hall of fame.
    VK, Nov 22, 2006
    #11
  12. Peter Michaux

    VK Guest

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


    What "our Doc" would really love is the requirement to post request
    only using a dedicated news reader, no web interfaces :) But it's
    silly first and a dispropagation by used software second :)
    VK, Nov 22, 2006
    #12
  13. In comp.lang.javascript message <>,
    Wed, 22 Nov 2006 02:50:36, Randy Webb <> wrote:
    >
    >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
    :mad:
    >



    Firstly, put a copy of the FAQ at a slightly new URL to be the
    FAQ-as-it-was.

    Then decouple the anchor-names in the FAQ from the appearance of the
    FAQ; making the references match the subsection numbers is a minor
    short-term inconvenience with long-term penalties. For example, change
    <a name='FAQ4_23'>
    4.23 How do I change print settings with window.print()?
    to use either name="aaabfd" (fixed arbitrary) or name='cpswp'
    (slightly mnemonic). No name should be reused for a different question.

    That means that sections can be added, removed, or renamed without
    concern for numbering/naming interaction.

    Put removed sections, if of any possible use, in an "Old Bits" document.
    Now, the link which led to Sec 4.23 will lead to the top of the FAQ. Put
    there, between title and index, a box saying something like "if you were
    expecting to reach a particular section and find yourself here, it may
    have moved into __http://.../OldBits.htm__. Select that and read on, or
    in your address bar change FAQ to OldBits and select GO to get directly
    to the section."

    Or write Body onLoad code that will read the desired URL's tail end
    (after #), compare it with the available anchors, and if not found jump
    to the right part of OldBits.



    In general, there are two ways in which the Web could be run.
    (1) No page is ever visibly changed or moved, though an invisible HREF
    may be updated to point to a better version. Then all links work in
    perpetuity - in some ways ideal, but not feasible.
    (2) Pages, links, URLs change from time to time. Links get broken. That
    actually works, and with moderate care the breakings are a minor
    inconvenience.



    While the FAQ should remain called a FAQ because "FAQ" is well-known, it
    should be subtitled with what a FAQ really is - a source of "Frequently
    Needed Answers".

    --
    (c) John Stockton, Surrey, UK. ?@merlyn.demon.co.uk Delphi 3? Turnpike 6.05
    <URL:http://www.merlyn.demon.co.uk/> TP/BP/Delphi/&c., FAQqy topics & links;
    <URL:http://www.bancoems.com/CompLangPascalDelphiMisc-MiniFAQ.htm> clpdmFAQ;
    <URL:http://www.borland.com/newsgroups/guide.html> news:borland.* Guidelines
    Dr J R Stockton, Nov 22, 2006
    #13
  14. In comp.lang.javascript message
    <>, Wed, 22 Nov
    2006 14:39:07, VK <> wrote:
    >> 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.

    >
    >Right: and if the Initial Request and Call For Votes (CFV) (if
    >followed) are both made as well-formed XML fragment then the
    >maintainer's task is as simple as copy-n-paste the final variant into
    >the relevant section (if voted YES).


    The maintainer's task would be very greatly simplified thereby, because
    the number of requests would be greatly reduced thereby.

    The idea of voting is REALLY STUPID. It empowers idiots, of which there
    is an ample supply. A FAQ maintainer must be selected as one of
    sufficient experience and judgement to be able to tell when there is, or
    will be, a general consensus among the /cognoscenti/ in favour of a
    particular change. He should be like the dog I had as a child; the dog
    listened to whatever he was told, and then did exactly what he wanted to
    do.


    In planning a FAQ-update system, one must allow for three distinct types
    of request, and anything between. Examples :-

    (1a) Message : "Please change the link XY1.htm#ab to be XY2#bc as I've
    shuffled my site."
    (1b) Message : "'Bated breath' is not spelt 'baited breath'; the latter
    will confuse many non-Anglos who try to look it up."

    (1) is no problem; the maintainer should usually be able to implement
    the change in the master copy while the requesting message is first
    open. Requesting in Mail (or by Web form) suffices. For (1b), it is
    not appropriate to request in News (except /en passant/); for (1a) it
    may be appropriate in by doubling as a public announcement.

    (2) Message from someone like (say) LRN : "I think FAQ 4.X should be
    improved; here's why; here's how". VK's method might work. However, if
    the FAQ maintainer is sure that LRN's words are, or can rapidly be
    converted to, a significant improvement, then the change should be
    implemented directly. Further discussion should be based on the new
    version.

    (3) A typical Google user has a problem apparently matching FAQ 4.Y, but
    cannot solve it with what 4.Y says. One can at most expect a cry for
    help by Mail, Mews, or Web-form. The article may have become inadequate
    because of changed browser circumstances, or may always have been
    inadequate; the article may be inadequately written, or the user may
    just be obtuse.

    A FAQ maintainer should not seek for perfection in each change; instead,
    he should seek for rapid improvement of any part known to need it.

    IMHO, it would be useful if each section, down to the 4.X or 3.X.Y
    level, were to be dated (as YYYY-MM-DD of course; no possible FFF
    inanities) with the date of the latest non-cosmetic change.

    It's a good idea to read the newsgroup and its old FAQ. See below.

    --
    (c) John Stockton, Surrey, UK. ?@merlyn.demon.co.uk Turnpike v6.05 IE 6
    <URL:http://www.jibbering.com/faq/> Old RC FAQ of news:comp.lang.javascript
    <URL:http://www.merlyn.demon.co.uk/js-index.htm> jscr maths, dates, sources.
    <URL:http://www.merlyn.demon.co.uk/> TP/BP/Delphi/jscr/&c, FAQ items, links.
    Dr J R Stockton, Nov 23, 2006
    #14
  15. In comp.lang.javascript message
    <>, Wed, 22 Nov 2006
    21:56:59, John G Harris <> wrote:

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


    Not necessarily. If the FAQ pages, with any CSS or JS include files
    needed, are routinely zipped together, then they can be readily
    downloaded as a unit and unzipped at leisure when off-line. The FAQ
    pages proper must include instruction on unzipping (FAQs are read by the
    naive) but that need only be "To fetch Zipped FAQ, read page _LINK_"
    with the linked page including "To download, _LINK_", both in slightly
    more words.

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


    Not necessarily. The division into Sec 4 (Mon/Fri) and Rest (Wed) was
    good, though I'd now suggest that Sec 4 need be posted only on Monday
    and Friday be used for something like "newish/future bits". Regulars
    would then not need to re-visit Mon & Wed sections every week.


    The FAQ is necessarily long (although Part 2 might be concentrated
    without loss) and really does need to be split, both for sheer size
    reasons and for ease of search (If I'm searching for something of
    Section-4 type, IE6 tends to search irrelevant sections). But Section 4
    should not be split into separate articles.


    > It's no use relying on people guessing the right search terms to use.


    Agreed. I spent some time searching for information on "idling" Windows
    XP as I was convinced that I needed a 5-letter word beginning with S
    (such as Sleep) and failed to think of "Stand-by". And I've still
    failed to find any mention of how to exit from Stand-by, except that it
    can require a password).

    --
    (c) John Stockton, Surrey, UK. ?@merlyn.demon.co.uk Delphi 3? Turnpike 6.05
    <URL:http://www.merlyn.demon.co.uk/> TP/BP/Delphi/&c., FAQqy topics & links;
    <URL:http://www.bancoems.com/CompLangPascalDelphiMisc-MiniFAQ.htm> clpdmFAQ;
    <URL:http://www.borland.com/newsgroups/guide.html> news:borland.* Guidelines
    Dr J R Stockton, Nov 23, 2006
    #15
  16. Peter Michaux

    VK Guest

    Dr J R Stockton wrote:
    > The idea of voting is REALLY STUPID. It empowers idiots, of which there
    > is an ample supply.


    Who would you call "idiot" from the currently proposed list? And how do
    you propose to take a decision without voting? By who's post came the
    last? By who screamed lauder and wrote nastier?

    > A FAQ maintainer must be selected as one of
    > sufficient experience and judgement to be able to tell when there is, or
    > will be, a general consensus among the /cognoscenti/ in favour of a
    > particular change.


    That would be too much of sinecura for FAQ maintainer :) because a
    "general consensus" is not possible among the people who wouldn't give
    up their rights to affect on FAQ content. That will be the same endless
    circus with each FAQ post followed by votum separatum, response on it,
    intensive discussion on who can speak English and who has a clue in
    JavaScript etc.

    > He should be like the dog I had as a child; the dog
    > listened to whatever he was told, and then did exactly what he wanted to
    > do.


    Right: and Dr.Stockton throwing the stick :)
    Truthfully I had the biggest doubts over your name while making the
    list proposal. From one side you are definitely an old cabbal member;
    from the other side (no offence this time) you are the most effective
    text obfuscation engine I know :) - you have a talent to bring a
    simple text to the level of no readability and always in the name of a
    better readability :) So I would like to see all textual changes being
    monitored by at least few more native English speakers.

    <snip>

    Truthfully, I'm getting a bit tired of this "now to improve our FAQ in
    the absolutely best way" discussion. It goes perpetually for two years
    by now: Congress doesn't take so long. I believe there is an agreement
    that Randy Webb is the next FAQ maintainer. If it's true then let him
    prove it by changing a single line in FAQ (to show server access). And
    let's the f start doing something.

    You don't want a strict procedure and voting? Fine. Just do it in the
    way you want it, I will not push my updates neither comment on FAQ
    posts now : so do not be accused of "spoiling the consensus".

    If it comes to nowhere again when it will be pretty much the end of FAQ
    as it used to be.
    VK, Nov 24, 2006
    #16
  17. Peter Michaux

    Randy Webb Guest

    VK said the following on 11/24/2006 9:16 AM:
    > Dr J R Stockton wrote:
    >> The idea of voting is REALLY STUPID. It empowers idiots, of which there
    >> is an ample supply.

    >
    > Who would you call "idiot" from the currently proposed list?


    He didn't say there was. He said the idea of voting empowers idiots, and
    it does. The very idea of it is STUPID.

    > And how do you propose to take a decision without voting?


    The same way it was done in the past. You tell the dog what to do and
    the dog does whatever he wants to do.

    > By who's post came the last? By who screamed lauder and wrote nastier?
    >> A FAQ maintainer must be selected as one of
    >> sufficient experience and judgement to be able to tell when there is, or
    >> will be, a general consensus among the /cognoscenti/ in favour of a
    >> particular change.

    >
    > That would be too much of sinecura for FAQ maintainer :)


    Nonsense.

    > because a "general consensus" is not possible among the people who
    > wouldn't give up their rights to affect on FAQ content.


    That is true. Not for reasons you think, but for the fact that anybody
    with Usenet access can "affect on FAQ content" and no, you wont *ever*
    get a consensus out of 100% of the people.

    > That will be the same endless circus with each FAQ post followed by
    > votum separatum, response on it, intensive discussion on who can speak
    > English and who has a clue in JavaScript etc.


    Time will tell.

    >> He should be like the dog I had as a child; the dog
    >> listened to whatever he was told, and then did exactly what he wanted to
    >> do.

    >
    > Right: and Dr.Stockton throwing the stick :)
    > Truthfully I had the biggest doubts over your name while making the
    > list proposal.


    Your doubts, and beliefs of people, has been shown in the past to not
    mean much. But you still didn't answer my question about that list.

    > From one side you are definitely an old cabbal member;
    > from the other side (no offence this time) you are the most effective
    > text obfuscation engine I know :) - you have a talent to bring a
    > simple text to the level of no readability and always in the name of a
    > better readability :) So I would like to see all textual changes being
    > monitored by at least few more native English speakers.
    >
    > <snip>
    >
    > Truthfully, I'm getting a bit tired of this "now to improve our FAQ in
    > the absolutely best way" discussion.


    Then why do you keep partaking in it other to complain about it?

    > It goes perpetually for two years by now: Congress doesn't take so long.


    This discussion has gone on for about two weeks now. This thread is 4
    days old according to Google. The post that started this discussion is
    dated from the 15th of this month. Today is the 25th. I am not sure what
    calendar you use but on the one I use, that is only 10 days.

    > I believe there is an agreement that Randy Webb is the next FAQ maintainer.


    That is my understanding to date but it is just as apt to change
    tomorrow as it is to stay the same.

    > If it's true then let him prove it by changing a single line in FAQ (to
    > show server access). And let's the f start doing something.


    The day I log into jibbering.com to change something to prove something
    to you will never come my friend. If my statement that I have server
    access isn't enough for you, then move on.

    > You don't want a strict procedure and voting? Fine. Just do it in the
    > way you want it, I will not push my updates neither comment on FAQ
    > posts now : so do not be accused of "spoiling the consensus".


    Don't make promises you can't keep. Nobody has said anything about you
    contributing (or not) to the FAQ. You have the same right anybody else
    does. You can make a request and then it either gets added or not. I can
    assure you of this though, if Richard won't approve your garbage
    entries, I won't add them either.

    <snip>

    --
    Randy
    Chance Favors The Prepared Mind
    comp.lang.javascript FAQ - http://jibbering.com/faq
    Javascript Best Practices - http://www.JavascriptToolbox.com/bestpractices/
    Randy Webb, Nov 25, 2006
    #17
  18. Peter Michaux

    Randy Webb Guest

    VK said the following on 11/22/2006 5:39 PM:
    >>> 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.

    >
    > Right: and if the Initial Request and Call For Votes (CFV) (if
    > followed)


    For the foreseeable future, it won't be followed.

    > are both made as well-formed XML fragment then the
    > maintainer's task is as simple as copy-n-paste the final variant into
    > the relevant section (if voted YES).


    The voting is a problem. Personally, I don't see a need for it as the
    people you propose to have on your list will only reply if there is a
    problem with it. To ask them to reply to say "I Agree" is, well, stupid.
    I just about know, without seeing them post, whether they would agree
    with something or not.

    > No one is asking from requestors to develop a full-scaled validating
    > XML document with prolog, matching DTD etc. The task is as simple as to
    > put properly a couple of tags and to use properly <del> and <ins> tags
    > (if request for update). If it constitutes too much of challenge for
    > some person, then most probably this person did not reach yet the level
    > to request any updates, she is still on the stage to *read* FAQ and ask
    > questions if something is not clear.


    Then why do you keep asking for entries in the FAQ? You should still be
    reading it and learning from it - based on your past history of posting
    here.

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

    >
    > Yes, before to request to change something, they have to read that
    > something in full and possibly in the context of surrounding topics.
    > They have to demonstrate an ability to navigate across the Web (at
    > least in the most primitive form), be able to hit the right button (at
    > least from the 3rd attempt) and be interested in improving group FAQ
    > (at least up to the level to spend extra 30sec for it). I see nothing
    > wrong in some most primitive medical and moral testing :) of a person
    > before a bunch of people will start discussing the request.


    I am not changing the way the FAQ gets changed. The current system is
    fine for now. Right now, I have no less than 50 posts to go through and
    try to get the FAQ updated first. It doesn't mean that it won't change
    in the future, it just won't be changed now.

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

    >
    > Great to have it confirmed.
    >
    >>> 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.

    >
    > This is what I meant.
    >
    >> 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.

    >
    > I did better :)


    No, you did not answer the question. I didn't ask for a list, I asked
    how you proposed to be able to add/remove people from that list. What
    criteria is to be set? And, who sets that criteria?

    > I started the list and I have shown how to possibly make it.


    Yes, but a list wasn't my question.

    > I posted the initial list, Matt Kruse asked to take him off
    > but added few more people. You may now add/remove your own names.
    > The others in the list is welcome to do the same. I personally do not like
    > too much the idea of "voters by honor":thus people who did not post at
    > c.l.j. for many years already yet included because they were great
    > posters 4,5,6 years ago. IMO that should be a practically usable list,
    > not a historical hall of fame.


    And my question still remains. What is the criteria to keep your
    proposed list idea "practical"?

    --
    Randy
    Chance Favors The Prepared Mind
    comp.lang.javascript FAQ - http://jibbering.com/faq
    Javascript Best Practices - http://www.JavascriptToolbox.com/bestpractices/
    Randy Webb, Nov 25, 2006
    #18
  19. In comp.lang.javascript message
    <>, Fri, 24 Nov
    2006 06:16:02, VK <> wrote:
    > I believe there is an agreement
    >that Randy Webb is the next FAQ maintainer.


    The newsgroup has not, AFAIR, been really asked its opinion on that.

    > If it's true then let him
    >prove it by changing a single line in FAQ (to show server access).


    There can be absolutely no doubt, when/if we have a new FAQ maintainer,
    that the middle of FAQ 8.1 Section 5.2 paragraph 1 needs changing, and
    the maintainer should have no difficulty in deciding how to change it.

    ISTM that the new maintainer's first completely-updated edition should
    be FAQ 9.0 (or higher), so that numbers between 8.1 and 9.0 could be
    used to label any intermediate versions.

    Until one has actually tried something, one never knows whether there
    may be some unsuspected difficulty. Therefore, ISTM wise that a new
    maintainer should ASAP alter the version at the standard jibbering URL -
    either by releasing a version with that paragraph changed, or by
    releasing either a re-dated version of 8.1 or a
    virtually-indistinguishable version of 8.1 with, say, the final
    full-stop doubled.

    --
    (c) John Stockton, Surrey, 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.
    Dr J R Stockton, Nov 25, 2006
    #19
  20. Peter Michaux

    Randy Webb Guest

    Dr J R Stockton said the following on 11/25/2006 1:58 PM:
    > In comp.lang.javascript message
    > <>, Fri, 24 Nov
    > 2006 06:16:02, VK <> wrote:
    >> I believe there is an agreement
    >> that Randy Webb is the next FAQ maintainer.

    >
    > The newsgroup has not, AFAIR, been really asked its opinion on that.


    And to date, nobody has disapproved of the notion either.

    >> If it's true then let him
    >> prove it by changing a single line in FAQ (to show server access).

    >
    > There can be absolutely no doubt, when/if we have a new FAQ maintainer,
    > that the middle of FAQ 8.1 Section 5.2 paragraph 1 needs changing, and
    > the maintainer should have no difficulty in deciding how to change it.


    That has been changed in the revised file I am working on.

    > ISTM that the new maintainer's first completely-updated edition should
    > be FAQ 9.0 (or higher), so that numbers between 8.1 and 9.0 could be
    > used to label any intermediate versions.


    It is numbered 9.0 and dated - tentatively - 2006-12-01.

    > Until one has actually tried something, one never knows whether there
    > may be some unsuspected difficulty.


    True, and right now my difficulty is in cscript and a script I can't
    make execute for me :\

    > Therefore, ISTM wise that a new maintainer should ASAP alter the
    > version at the standard jibbering URL - either by releasing a version
    > with that paragraph changed, or by releasing either a re-dated version
    > of 8.1 or a virtually-indistinguishable version of 8.1 with, say, the
    > final full-stop doubled.


    The .xml file I am working on is at http://jibbering.com/faq/newfaq/ but
    I can't get the index.html file autogenerated for me right now but the
    new version has the name changes, along with a lot of other things
    changed so far.

    --
    Randy
    Chance Favors The Prepared Mind
    comp.lang.javascript FAQ - http://jibbering.com/faq
    Javascript Best Practices - http://www.JavascriptToolbox.com/bestpractices/
    Randy Webb, Nov 26, 2006
    #20
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Bjorn Jensen
    Replies:
    0
    Views:
    1,188
    Bjorn Jensen
    Mar 22, 2005
  2. SteveM
    Replies:
    5
    Views:
    1,573
    Mark Rae [MVP]
    Aug 28, 2007
  3. UI makeover

    , Dec 18, 2007, in forum: ASP .Net
    Replies:
    4
    Views:
    340
  4. Berger, Daniel

    The RAA needs a makeover

    Berger, Daniel, Sep 20, 2006, in forum: Ruby
    Replies:
    1
    Views:
    104
    John Gabriele
    Sep 21, 2006
  5. Peter Michaux

    Suggestion for FAQ notes scroll value script

    Peter Michaux, Nov 14, 2006, in forum: Javascript
    Replies:
    0
    Views:
    80
    Peter Michaux
    Nov 14, 2006
Loading...

Share This Page