Hi Ian,

On Mon, Mar 1, 2010 at 6:04 PM, Ian Trudel <ian.trudel at gmail.com> wrote:
> You're not on the board just yet and I welcome a sense of direction from you. :)

there is and will always be - I was trying to give it to you; it's at
another level. Please accept that I do not want to fix any plans just
yet. I am collecting ideas. I really want to understand what is
important and help moving that forward. Improving documentation both
inside and outside the image (inside: rather API documentation,
outside: rather tutorials or even more complex things) is what I
intend to advance.

Sorry if it's not any more clear to you, but that's what I intend to
do at the "political" level - and board membership is such a thing.
:-)

>> You got me wrong there; I'm not about *this* level of entry. There is
>> a level between that of the Etoys target audience and (S/P)BE or laser
>> game adopters, and my idea of an intro book for children targets
>> precisely this level.
>
> Thanks for the clarification. We've talked about children using Squeak
> during last year but it's not a good demographic. They're not going to
> get involved in developing Squeak itself before another, say, 15
> years. My opinion is that the target audience should be Squeak
> developers and the rest will naturally follow in due time.

Ah well, OK, misunderstanding again, this time, I was not clear
enough. This was not to say I'm happy with the amount of documentation
available for those in the focus of Etoys or full-fledged advanced
Squeak. But there is a hole in the middle between those, and this is
what the intro book item in my list is about.

The documentation thing is certainly more than just one strain of work ...

> I understand your point. I am very much for a documentation team. It
> wouldn't hurt to have a more specific plan/direction from you, even if
> it does not include concrete solutions.

Anything I write will be too meta for you. :-)

Anyway, here's an attempt.

First, form a documentation team representing different stakeholders,
identify issues that need to be addressed (poll?), think about how to
address those (technically, socially, whateverly).

Next, come up with solutions that can advance in close connection to
the advancement of the trunk (documentation not necessarily hard-wired
with single packages, but connectable, versionable, (un)installable,
and appropriately updateable - this is rather about in-image "API"
documentation). The overall idea is to keep the documentation in sync
with the system. Also, sketch tutorials on identified issues, ask
experts (developers?) to contribute, have them completed and posted
and, afterwards, kept up-to-date. These ideas will require ongoing
efforts on behalf of everyone involved.

Meantime, in a different branch, think about how to shape and create
an entry-level book for the target audience mentioned above. Find
people that want to contribute, agree on contents and structure, write
write write, throw at people, see how it works, refactor, etc.

This *will* take more than a year. But these things just have to be
kicked off some time. Squeak is just too good to be under-documented,
it does not deserve this.

Best,

Michael