Forum: Rails Spinoffs (closed, excessive spam) Prototype FAQ

Hi all,

In the discussion about renaming/replacing this group, a few of us
mentioned a FAQ.  If there's a FAQ somewhere, it's reasonably well
hidden. :-) In that other thread, kangax wrote:

> I have started on a FAQ some time ago. It's fairly basic, but could be
> a good start

Excellent!   We have a starting point (and knowing kangax, his
"starting point" is probably where most people thing "Yeah, okay,
that's good enough for now.").

In terms of hosting it and keeping it possible for people to improve
it, I see a couple of options:

1. Fairly obvious, we could host the FAQ on Google Groups as a "page"
attached to the users group and allow either members or (if there's a
problem with malicious edits) managers to edit it.

Pros: A) It's attached to the group and so quite easy to find if
you're using the web interface; B) Google Groups pages are fairly easy
to edit; C) Groups provides reasonable controls over the pages along
with basic versioning; D) Same member/manager/owner stuff that applies
to the group applies to the pages.

Cons:  A) The UI is nice for simple things but doesn't even provide a
means of doing preformatted sections or anchors, both of which seem
important for a code-related FAQ -- instead, you have to use the Edit
HTML feature; B) It's attached to the group, rather than to Prototype
(yes, I know that was also a "pro").

2. I can't help but notice that GitHub provides wikis for projects, so
if the core team want, we could put it somewhere on
http://github.com/sstephenson/prototype/wikis.  I'm probably not
familiar enough with GitHub to do a proper pros and cons for it, but:

Pros:  A) It's attached to Prototype rather than the group; B) It's a
proper wiki.

Cons:  A) Completely different set of users and permissions (Git vs.
Group); B) Less obviously associated with the users group.

Off the cuff, I lean toward hosting it on the group's "pages" despite
the failings of Google's editor (I mean, we can all just about edit
HTML, right?).  We can also use Pastie (http://pastie.org) for
questions/answers involving any significant amount of code, although
usually it's oneliner stuff we can do inline.

I lean toward the pages rather than GitHub for two reasons:  A) Having
the same members/managers/owner stuff for the FAQ as for the group
seems like a good idea, B) Of the two choices above, for me
associating it with the group (user land) rather than GitHub
(developer/committer land) makes sense.

Thoughts?
--
T.J. Crowder
tj / crowder software / com

Hi T.J.,

Why not host in on the prototypejs.org website ?

Ultimately, we might actually need two FAQs:

One, general, on the Prototype website, another one, more specific
(problem solving related, really) on the Google groups page.

Thoughts ?

Tobie

Hey Tobie,

Sounds great!

For me the key thing is to have at least one FAQ that the community
can contribute to directly.  If we can do that on prototypejs.org
without taking someone's time away from other things, that's a clear
winner.  If not, though, just linking to the FAQ from prototypejs.org
should be plenty good enough.

Your two FAQs thing makes sense to me if we can clearly define the
difference in mission between them.  Perhaps that difference might be
as simple as:  One of them is maintained by core and "official", the
other is maintained by community and therefore caveat emptor. :-)

Sadly, I'm not enough of a believer in humanity that I see a
completely open, anonymous wiki -- which means dealing with user
management, permissions, etc.  Hence my taking the easy way out and
using a Google Group page (for now, anyway).
--
T.J. Crowder
tj / crowder software / com

Hi again,

An anonymous wiki clearly wouldn't work, you're absolutely right.

I've thought a bit more about this and end up thinking I'd be in favor
of a unique FAQ page on the Prototype website.

Maintaining two different FAQs and figuring out where what belongs is
just going to be a pain.

I also think that these FAQs would belong on the prototypejs.org
website as it's the point of entry to the framework.

We probably should separate those FAQs in a series of categories, for
example:

GENERAL
- What is Prototype?
- Under which license is it released?
- How do I download it?

CONTRIBUTING:
- where can I report bugs?
- what versioning system is Prototype using?
- how do I download the source code?

COMMON GOTCHAS:
- I'm getting a foobar error, what does that mean?
- My Ajax.Request doesn't work (SOP)

etc.

I'm willing to set up and maintain a FAQ page on the website provided
new FAQ's are emailed to me directly in Markdown format.

Let me know what you think.

Best,

Tobie

Hi Tobie,

Having one official FAQ on the prototypejs.org website sounds great.

The mechanism sounds a bit manpower-intensive, though, particularly
for you.  For example:  I send you a FAQ entry, you glance at it and
post it, and then I see a typo in it -- doh!  Fixing my typo then
means my emailing you and you taking the time to go fix it; that's
just a waste of your time.  I'd rather see something more directly
community-managed, with history and a log of what user did what (for
accountability), etc., etc. -- e.g., a wiki or similar.

Now, of course, we can have that on prototypejs.org.  There's lots of
wiki software out there, or wiki.prototypejs.org could be hosted on a
wiki service like WikiSpaces or similar.  But then we start getting
into someone (you?) spending the time to set that up and maintain it,
yet another user list to manage, etc., and I'm sort of trying to avoid
adding things to peoples' plates.

At the end of the day, I'll happily use what's there. :-)  For me,
it's more important that it be fairly (but not completely) open than
that it be actually on prototypejs.org; if we can have both without
too much effort, great, but otherwise I'd go for the quick and easy
solution for now.
--
T.J. Crowder
tj / crowder software / com

hey!

Tobie Langel a écrit :
> etc.

And also, out of the top of my head:

“
WHERE CAN I GET HELP?
- The archive of the former official support GGroup (4,300+ threads)
- The official support GGroup
- IRC

HOW CAN I LEARN ABOUT PROTOTYPE?
- Books
- Websites
- Technical blogs
- Conferences

WHERE CAN I GET THIRD-PARTY CODE?
- Scripteka
- …
”

--
Christophe Porteneuve aka TDD
tdd@tddsworld.com

T.J. Crowder a écrit :
> At the end of the day, I'll happily use what's there. :-)  For me,
> it's more important that it be fairly (but not completely) open than
> that it be actually on prototypejs.org; if we can have both without
> too much effort, great, but otherwise I'd go for the quick and easy
> solution for now.

Not everybody can achieve Wikipedia quality.  Closer to home, the wiki
for Scripty went pretty rough over the years, ending up
incomplete/obsolete/inconsistent/rogue…

Perhaps we could find some moderated system to contribute to FAQ pages
on the GGroup itself, in addition to a general FAQ on prototypejs.org?

In that case, I'd be leaning towards the dual-FAQ approach you
mentioned, with a general-purpose, fairly static one @ prototypejs.org
and a common-questions FAQ moderated on the GGroup.

--
Christophe Porteneuve aka TDD
tdd@tddsworld.com

> Not everybody can achieve Wikipedia quality.

Indeed not. :-)  And even though MediaWiki is fairly easy to install,
that's just the beginning of the process.

> Perhaps we could find some moderated system to contribute to FAQ pages
> on the GGroup itself, in addition to a general FAQ on prototypejs.org?

That's why I was thinking we'd use a Google Group "page" for this:
We'll already have a user list in place, managers volunteering to
handle new members, etc., etc.  We can either leave the FAQ page open
for edits by all members until/unless there's a problem, or we can
only let managers modify the page.  Google Groups has those options
available (on a per-page basis, with defaults).
--
T.J. Crowder
tj / crowder software / com

GGroup-based FAQ sounds like the way to go. I absolutely don't mind
maintaining it regularly. I'm not quite sure about having an
"official" FAQ on a prototypejs.org - home page could simply be
pointing to the one on GGroup (where one could both read FAQ and ask
questions)

- kangax

Hey

Just a thought, but most of us are web developers here.

I'm not really one for reinventing the wheel, but surely it wouldn't be 
hard
to produce a markdown-content-driven faq where it's easy to add and 
remove
articles and the "published" ver of the faq is processed markdown.

Just a thought, i'd even have a go at writing it, if i wasn't so crazy 
busy
that I barely find time to read the group :)

Gareth

Hi all,

I've been chatting with Tobie about this and about moving the group,
both of which he and Core are really supportive of.

He's very keen that the FAQ be on prototypejs.org, which for the
moment means that in order to add to / correct it we have to email one
of the core committers with changes (in markdown format), and they'll
update the website.  Tobie's committed to taking on doing those
updates if we send them to him.  (As you know from my comments in this
thread, I would prefer something less locked-down and more community-
managed and I've made that point again, but apparently there have been
recent issues on that which I'm not privy to the details of -- e.g.,
this isn't random authoritarianism.)  Obviously if we want to, we can
have our own unofficial users FAQ on the group as well.  There are
pros and cons to having two different FAQs.  FWIW, I'd recommend we
start out with one (which would be more than we have now!) and only do
a second one if we can come up with a clear distinction between the
two.

So kangax and I are putting together a quick first take.  Right now
the ball is in my court, he's already done his part (see the link
earlier in this thread) so as soon as I can get an hour or two
together I'll take his stuff, Tobie's suggested layout, kangax's
additions to that, and my own thoughts and ideas and put together a
v0.1.  I'll post that here for comment/discussion/"oh my god, man,
what are you thinking, this is terrible!"/whatever. ;-)
--
T.J. Crowder
tj / crowder software / com

Okay, folks, I've made a start on it.  Very draft, and most of the
credit for real content goes to Kangax.  I've posted a copy for
collaboration purposes only as a page on this group:

http://groups.google.com/group/rubyonrails-spinoff...

It's in Markdown format.

Input and editing very welcome indeed.  I didn't do the collect-all-
the-links-at-the-end because you either A) Uses numbers, and
inevitably spend unnecessary time renumbering, or B) Use symbolic
names, which interfere with the text.  Most of the time I just opted
for inline links instead.

Looking at this, we should probably resurrect the "two FAQs" idea, one
on prototypejs.org consisting of the first five sections of this
thing, and one on the new group that members can edit which is the
"Common Questions and Answers" section.  I think this was suggested by
someone, and then for some reason we went away from it, but doing it
brought home to me that there is a clear line of delineation.
--
T.J. Crowder
tj / crowder software / com

*SIGH*

The Google Groups Pages editor can't handle the preformatted stuff, it
makes a TOTAL pig's breakfast of it when you go back in.  I really
wanted people to be able to directly edit the FAQ-in-progress, but for
now here's a link to the static draft:

HTML: http://www.crowdersoftware.com/tjc/ptemp/prototype.faq.html
Markdown: http://www.crowdersoftware.com/tjc/ptemp/prototype.faq.text

Post Markdown diffs to this thread and I'll incorporate them as/when I
can.
--
T.J. Crowder
tj / crowder software / com

On Jun 17, 11:22 am, "T.J. Crowder" <t...@crowdersoftware.com> wrote:
> Your two FAQs thing makes sense to me if we can clearly define the
> tj / crowder software / com
Hi.

I'm a member of the PHPDoc team (not the editor just a contributor).

There are 3 things I rely on.

1 - The DocBook 5 standardised XML files held in CVS - the official
documentation.
2 - The user-submitted notes.
3 - PhD - the PHP based rendering tool to convert the XML into the
different formats (html - single file and multi file, php - for
embedding into the php.net site and mirrors, chmsource - for
compilation into a Windows CHM file).

These 3 things together make the manual.

I would say that the prototypejs.org site should hold all the
documentation / FAQs. Users are not going to github for docs/faq.

Allowing user-submitted notes allows for normally good additional info
coming in without the need of permissions.

Using a standardised format like DocBook 5 would allow third party
rendering tools to be able to produce pretty much any output format
you need.


I would say that having user notes and comments as part of the
documentation provides a greater resource than having users searching
mailing list archives.

Hi all,

On Jun 21, 3:22 pm, "T.J. Crowder" <t...@crowdersoftware.com> wrote:
> HTML:http://www.crowdersoftware.com/tjc/ptemp/prototype.faq.html
> Markdown:http://www.crowdersoftware.com/tjc/ptemp/prototype.faq.text

In the absense of input, let's call what we have good and get it
posted so we can start the switchover to the new group.  We can fill
in the TBDs and generally improve things over time.  "Perfection
kills" as I believe someone put it... ;-)

Tobie, would you post it to prototypejs.org?

Thanks,
--
T.J. Crowder
tj / crowder software / com

Hi,

I've reformatted some of the markdown that was behaving weirdly:
http://pastie.org/private/sn1degqyrejhb4ue0hs2w

Can we clean this up before we post it ?

Remove the TBD, make links labeled 'here' a bit more explicit, etc.

Best,

Tobie

Hi Tobie,

> I've reformatted some of the markdown that was behaving weirdly

Pastie's been down for me all day, I'll take a look when it comes back
up or if you have a copy, email it to me.  The markdown that was there
was fine for the official markdown at daringfireball, but if the CMS
you're using for prototypejs.org doesn't like it, no harm in doing
what it likes.

> Can we clean this up before we post it ?
>
> Remove the TBD, make links labeled 'here' a bit more explicit, etc.

Sure, I can just remove the TBDs until/unless someone wants to
contribute them.  Could make the "here"s more explicit if you like (or
you can), but the CSS at prototypejs calls out links pretty clearly.
--
T.J. Crowder
tj / crowder software / com

Hi again,

Pastie is back up and I've got your copy, looks like it was just the
target anchors that were causing a problem, so you switched to using
HTML for the headings and setting their IDs.  Good good.

I'll do the other stuff and paste an updated version.
--
T.J. Crowder
tj / crowder software / com

Hi all,

Updated copy with Tobie's markdown edits, the TBDs removed, and most
of the "here"s made a bit more obvious (although again, the CSS on the
site is the main way links should be highlighted):

http://www.crowdersoftware.com/tjc/ptemp/prototype.faq.html
http://www.crowdersoftware.com/tjc/ptemp/prototype.faq.text

the previous version is available for comparison:

http://www.crowdersoftware.com/tjc/ptemp/prototype...
http://www.crowdersoftware.com/tjc/ptemp/prototype...
--
T.J. Crowder
tj / crowder software / com

Hi,

Thanks, I'll check it out asap.

Regarding links: http://www.useit.com/alertbox/weblogs.html (see 4.
Links Don't Say Where They Go).

Best,

Tobie

Hi Tobie,

> Regarding links:http://www.useit.com/alertbox/weblogs.html(see 4.
> Links Don't Say Where They Go).

It's totally standard practice.  We'll just have to agree to
disagree.  Any you want to edit, obviously you're welcome to do so!
I'm just trying to get something finished and posted.
--
T.J. Crowder
tj / crowder software / com

On Jun 30, 5:46 pm, "T.J. Crowder" <t...@crowdersoftware.com> wrote:
> It's totally standard practice.

Yeah, so are table-based layouts ;)

UH SNAP.... oh no he di'nt!!



On Mon, Jun 30, 2008 at 7:05 PM, Tobie Langel <tobie.langel@gmail.com>
wrote:

>
>
>
> On Jun 30, 5:46 pm, "T.J. Crowder" <t...@crowdersoftware.com> wrote:
> > It's totally standard practice.
>
> Yeah, so are table-based layouts ;)
> >
>


--
Ryan Gahl
Manager, Senior Software Engineer
Nth Penguin, LLC
http://www.nthpenguin.com
--
WebWidgetry.com / MashupStudio.com
Future Home of the World's First Complete Web Platform
--
Inquire: 1-920-574-2218
Blog: http://www.someElement.com
LinkedIn Profile: http://www.linkedin.com/in/ryangahl

Hi Tobie,

Again, you're welcome to change what you want in the process of
putting it up on prototypejs.org.  I'm not invested in the form of the
links, f'chrissake. :-)  But let's move forward already!
--
T.J. Crowder
tj / crowder software / com