Documentation Improvements

[aaronjudd]

I would like to see friendlier documentation:
a) single source searching
b) include user comments

The two cases of great documentation that I reference daily that highlight the two features I am suggesting are:

Mysql
http://dev.mysql.com/doc/refman/5.0/en/

PHP
http://www.php.net/manual/en/

Particulary the php documentation, always provides great user insight. If I learn something valuable I would be happy to post it back to the Laszlo documention, but certainly not to the forums (if it's not a question )..

As for the Wiki - well the search doesn't even work there. (as least for an ignorant user like myself ;-) )

[aaronjudd]

Also, open up,or at least allow moderated posts to the "Tip of the Week" forum thread. I have a couple tips I could share, as I am sure other do as well, and it sort of looks like the last tip of the week might have been the tip of the last year.

[jsundman]

Hello Aaron,

Thanks for your suggestions. We have discussed improving the searchability and allowing users to add comments, and would like to address both of these areas. Resources don't allow us to do so now, but I hope that we'll be able to get to them soon.

Over this summer, the OpenLaszlo team will be taking a look at revamping the doctools as part of porting them to 4.0. Because the internal representation of classes is changing for 4.0 (in order to support compiling to different runtimes such as Flash 6, 7, 8 and 9 and DHTML), we need to overhaul the tools that generate the reference. A different set of tools is used to generate the Developer's Guide. With luck we'll be able to improve searchability, and maybe we'll be able to add the "user comment" capability too.

Our first priority is to make sure that we don't have any regressions; after that we'll see if we can make any enhancements.

We welcome your participation in this process. On the OpenLazlo mail list (sign up at OpenLaszlo.org), Ben Shine sent out a memo today asking for suggestions for improving the documentation tools as part of the OpenLaszlo 4.0 effort. Now would be an opportune time to join that discussion.

As for the Tip of the Week, your point is well made, and I'll pass your suggestion to Amy Muntz, the Openlaszlo program manager.

[aaronjudd]

John, thanks for the reply - all good points.

I am on the mailling list, and I saw that posting - I don't have much to add other than my points here, but I will be sure to get more actively involved over there as well, and let the thoughts be known.

As another comment, since you mention the mail lists:

On the mailling lists and the wiki also - it seems odd to be running all these different services, when it might be easier and more convienant to run them as one.
IE: the mailling list is often being used for the same purposes as the forum, why should the list / forums not just be a reflection of each other.
I have seen sites/services with combined list/forum/chat/rss functionality work quite well, as it gives everyone their own flavour.

[aaronjudd]

Just FYI: from the mailling list:

*********************************
On Jun 12, 2006, at 7:37 AM, Andrew Chandler wrote:

I think perhaps the problem is that a lot of developers, myself included are
busy enough that if we have to "go look" as opposed to "it shows up" then
even though the amount of effort isn't that much different the "go look"
will happen less frequently. I think the difference comes down to my email
client TELLS me I have new laszlo mail whereas I have to go look at the
forums on the chance there MIGHT be new mail there. Too bad they just
aren't linked so that you could use either mechanism.



-----Original Message-----
From: laszlo-user-bounces@openlaszlo.org
[mailto:laszlo-user-bounces@openlaszlo.org] On Behalf Of Matthew Cloy
Sent: Monday, June 12, 2006 8:55 AM
To: Martin Allchin
Cc: Laszlo-user@openlaszlo.org
Subject: Re: [Laszlo-user] is this mailing list linked to the forum on
openlaszlo.org ?

I use the forums extensively,

More than the mailing list, in fact... as do many others. The only problem
with the forums is that there's a reasonable amount of white noise there.
Lot's of basic questions, and actually getting an informed reply on a more
complex topic is sometimes hit an miss.

(For example, I was trying the other day to find out how to inject things
into the class prototype of view so I could add stuff to the base
functionality of dynamically allocated classes without having to modify all
the components, the answer I got was <class name="x" extends="view">, glad
someone was at least trying to help, but not quite what I was after..... :)

My heuristic for posting seems to be to search in the forums first, post in
the forums second, and if I get no answers there (or don't figure it out
myself by then, which I normally have) then I'd post here as that's where it
seems the Laszlo guys hang out.

(Note: There does seem to be a big difference between how much the more
experienced and core Laszlo developers post on the mailing list as opposed
to checking the forums, maybe I'm wrong, but if not then it would probably
be good PR to have a look at the forums a little more often as it sometimes
seems as though the more experienced developers have abandoned it as a ghost
town. ;)

Anyway, my 2c worth.
Cheers!
Matt


Martin Allchin wrote:
Personally I think forums are a better medium for exchanging knowledge
as they're categorised and searchable -- It's a shame no-one used the
Laszlo forums, one of the projects least used assets.

Jim Grandy wrote:

Ran,

No, it's not. They are separate.

jim

On Jun 10, 2006, at 4:27 PM, Ran wrote:


Hi,
Is this mailing list linked to the forum on openlaszlo.org ?

Thanks,
ran
_______________________________________________
Laszlo-user mailing list
Laszlo-user@openlaszlo.org <mailto:Laszlo-user@openlaszlo.org>
http://www.openlaszlo.org/mailman/listinfo/laszlo-user

---------------------------------------------------------------------