2010/3/1 Michael Haupt <mhaupt at gmail.com>:
> Hi Ian,

Hello Michael,

> 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.

Sure, I understand. I was outlining the fact that one runs for the
board and gets elected: it means to have a plan and be appealing to
the voters.

> 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 ...

My point is also that Squeak developers need a good motivation to work
on the ideas proposed. Anything addressed to children won't cut it
because we have no immediate use for it. This is perhaps where the
trunk comes successful because it is self serving and it generates
motivation and energy.

> Anything I write will be too meta for you. :-)
>
> Anyway, here's an attempt.

You're doing a fine job, Michael.

> 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).

I agree and I like your idea to query the community with polls.

> 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.

See, a plan is taking shape. It's important to write these things down
even when it's obvious, then we can bounce ideas to each other in a
productive manner.

Thanks for the clarifications!

Ian.
-- 
http://mecenia.blogspot.com/