Re: Fluid documentation

I am reminded of when I was active in the PHP community. PHP  
documentation seems to have been designed to be a little thin, just  
the spec and very little usage, but every page of the docs had  
comments, and the community actively contributed commentary, and the  
comments are an official part of the documentation distribution.

The comments covered everything from quirks to usage to whatever,  
usually in the form of "I'm trying to do x, and I keep getting y" and  
then someone responding with, "Ah yeah, I figured that out, here's my  
code <?php ..." and then someone else writing back, "That's cool but  
here's a better way: <?php ..." and so on and so on.

Since PHP has now been around _forever_, the commentary is now the  
bulk of the documentation, and, to me, the most useful part of the  
documentation. Most of the PHP that I learned, I learned from reading  
the commentary.

Fluid is much more of a moving target than PHP is (for now) and I  
don't think that we're at the point where relying on our comments  
would make sense. But once we are more mature and stable, this is one  
viable approach. The trick is cultivating that culture of comments.

- Eli

On Oct 8, 2008, at 11:59 AM, Anastasia Cheetham wrote:

. . . . . . . . . . .  .  .   .    .      .         .              .                     .

Eli Cochran
user interaction developer
ETS, UC Berkeley


_______________________________________________
fluid-talk mailing list
fluid-talk@...
http://fluidproject.org/mailman/listinfo/fluid-talk