[squeak-dev] Documentation Team

Casey Ransberger casey.obrien.r at gmail.com
Thu Aug 26 00:34:04 UTC 2010


+1 to the docs site. 

I'd attack it by hooking into the help system from Seaside, and generate search engine friendly URLs based on the topic. 

Help system can already give us a quick and dirty "API reference" in addition to the hand written docs, and I'd want to arrange for that to be visible from the web as well. 

That said, I think the web facing docs are a lower priority than gettin some good documentation written. 

A web interface is a chunk of work, and I'd (or someone anyway) need to find the time to get it done. I'm confident that I could get it done if I had an infinite supply of monkeys, virtual machines, and time, however. 

(Seriously, shouldn't be too bad, but these things always take at least twice as long as one thinks they will...)

On Aug 25, 2010, at 4:08 PM, "Jecel Assumpcao Jr." <jecel at merlintec.com> wrote:

> I would like to thank Michael Haupt, Nicolas Cellier, Hannes Hirzel and
> Casey Ransberger for investing their time in this discussion. I agree
> with what has been said so far, but perhaps we should step back a bit
> and try to define what will be the scope of the documentation and how it
> will be presented.
> 
> About the who, I fully agree this will be a job for everybody and not
> just the Documentation Team. I see a team like this as a group that will
> create the necessary infrastructure and might even act as editors, but
> the authors are a separate group (it will be great if people want to be
> a part of both, of course).
> 
> Of course we have methods comments and class comments, but I think there
> is no limit to the kind of in-image documentation we can have. And if
> the trend is towards a smaller kernel with loadable stuff, the bulk of
> this documentation could be in the form of loadable packages. Using the
> same tools and proceedures as for evolving the code is certainly a good
> option (though this might require extending those tools a bit).
> 
> One important feature for the documentation is to make it more easily
> available outside of Squeak. I don't like to write the same thing twice,
> but imagine that we could create a doc.squeak.org site running a fully
> loaded image and automatically exporting all the documentation in a form
> that people and web crawlers can use.
> 
> These are just some ideas to keep the ball rolling.
> 
> -- Jecel
> 
> 



More information about the Squeak-dev mailing list