JSAN comments / suggestions from a newbie
Klortho
effort has gone into JSAN, and there's some very cool stuff in it.
Take this post for what it is, the first impressions of a guy who
stumbled on it recently, who's in the midst of learning JavaScript and
getting to the point of playing with some librarires.
Also, more in the way of background: I have some Perl experience --
not much, but back in the day I contributed Physics::Unit (http://
search.cpan.org/~klortho/). I like Perl a lot, but I've never been a
fan of CPAN. But this post isn't about CPAN, its about JSAN:
General
* The site is too developer-centric rather than user-centric. By
that I mean that the *first* thing people should see when the hit the
site is how to find and use the modules, as opposed to information
about how to write their own modules and contribute to the site.
* There's too much Perl in JSAN. One goal should be to eliminate
Perl dependencies as much as possible. Don't assume that your users/
developers are experienced Perl programmers.
* Along those lines, there needs to be a "Getting Started" page
with instructions for using the modules in your web pages. I think a
user should be able to use them directly off the JSAN server, but it's
not clear to me that that's even possible.
The website static content
* A wiki, or something similar, for the website static content
itself. If not a wiki, it seems to me that the website page sources
should be part of the project - any committer should be able to make
changes.
* What is Planet JavaScript (http://planet.openjsan.org/)?
The archive:
* The search mechanism needs to be very intuitive and simple-by-
default, but powerful when needed. For an archive like this, the
search feature is probably the most important bit.
* Right now, is there any way to get a list of all the extant
modules? Looking for this practically made me tear my hair out in
frustration.
* What's the difference between "Libraries", "Distributions", and
"Releases"? It's confusing.
The modules
* The documentation of the modules is hideous. I would badly want
to see a move away from POD and maybe towards something that could
extract structured documentation from the source automatically. At any
rate, the documentation for modules should be semantically structured
and consistent, so that it's consistently scriptable.
* As an example of what could be done if the documentation is
structured, the brief description for each module (for example, the
"Simple Javascript Ajaxing" in "Ajax - Simple Javascript Ajaxing")
could be extracted and made to appear in the search results, or in the
home page under "Distributions".
* Philosophically, I tend to lean more towards requiring modules
to meet some minimum standards for documentation and testability,
rather than the "we'll take anything" mode it's in now.
Cheers!
Nickolay Platonov
http://extjs.com/deploy/dev/docs/
Such documentation automatically generates from sources, (which should use ScriptTag markup).
There is also an open-source parser:
http://code.google.com/p/jsdoc-toolkit
More info about markup:
http://code.google.com/p/jsdoc-toolkit/wiki/TagReference
Would be great if you can contribute any from mentioned features.
Regards, Nickolay
David E. Wheeler
> Pardon me if I step on any toes in this post. I know that a lot of
> effort has gone into JSAN, and there's some very cool stuff in it.
> Take this post for what it is, the first impressions of a guy who
> stumbled on it recently, who's in the midst of learning JavaScript and
> getting to the point of playing with some librarires.
> Also, more in the way of background: I have some Perl experience --
> not much, but back in the day I contributed Physics::Unit (http://
> search.cpan.org/~klortho/). I like Perl a lot, but I've never been a
> fan of CPAN. But this post isn't about CPAN, its about JSAN:
I think that anyone who is willing to generate discussion and
contribute code should be welcomed with open arms. You can't really
step on any toes; nothing much has happened recently, and actions
speak louder than words.
But “never been a fan of CPAN”?? I think that's a first. :-)
> * The site is too developer-centric rather than user-centric. By
> that I mean that the *first* thing people should see when the hit the
> site is how to find and use the modules, as opposed to information
> about how to write their own modules and contribute to the site.
+1
> * There's too much Perl in JSAN. One goal should be to eliminate
> Perl dependencies as much as possible. Don't assume that your users/
> developers are experienced Perl programmers.
Well, I don't think that you should need Perl to use the site or any
of the libraries you download. But it can be useful for JSAN library
developers to use (Module::Build::JSAN), and you can make use of
JSAN.pm if you want a command-line interface to the site. But I agree
that the site itself and its API should display no Perl dependencies.
> * Along those lines, there needs to be a "Getting Started" page
> with instructions for using the modules in your web pages. I think a
> user should be able to use them directly off the JSAN server, but it's
> not clear to me that that's even possible.
+1. Most folks will want to download the libraries for production use,
though. Or to avoid cross-site scripting issues.
> The website static content
>
> * A wiki, or something similar, for the website static content
> itself. If not a wiki, it seems to me that the website page sources
> should be part of the project - any committer should be able to make
> changes.
I think it will be in the Git repository that John plans to set up.
> * What is Planet JavaScript (http://planet.openjsan.org/)?
It was a blog aggregator for JSAN authors. It needs some love -- or
abandonment.
> The archive:
>
> * The search mechanism needs to be very intuitive and simple-by-
> default, but powerful when needed. For an archive like this, the
> search feature is probably the most important bit.
+1
> * Right now, is there any way to get a list of all the extant
> modules? Looking for this practically made me tear my hair out in
> frustration.
Don't follow you there. The home page has a list of distributions
(kinda stupid, really); what is it you're looking for, exactly?
> * What's the difference between "Libraries", "Distributions", and
> "Releases"? It's confusing.
Yeah, we need to standardize the terminology and put it in a FAQ.
> The modules
>
> * The documentation of the modules is hideous. I would badly want
> to see a move away from POD and maybe towards something that could
> extract structured documentation from the source automatically. At any
> rate, the documentation for modules should be semantically structured
> and consistent, so that it's consistently scriptable.
I've become a huge fan of Markdown since I wrote Test.Simple (which is
likely where the dependency on POD originated). I'd love to see
markdown support added to Module::Build::JSAN, perhaps with an option
to extract it from the source.
> * As an example of what could be done if the documentation is
> structured, the brief description for each module (for example, the
> "Simple Javascript Ajaxing" in "Ajax - Simple Javascript Ajaxing")
> could be extracted and made to appear in the search results, or in the
> home page under "Distributions".
The search engine is currently just a hack. I think It just looks at a
list of library names in a YAML file. It was intended as a placeholder.
> * Philosophically, I tend to lean more towards requiring modules
> to meet some minimum standards for documentation and testability,
> rather than the "we'll take anything" mode it's in now.
Well, that's not the *PAN way. I don't think we're really interested
in creating an approval process -- that's the reason that Pear is not
nearly as successful as CPAN, IIRC.
Best,
David