On 8/25/10, Michael Haupt <mhaupt at gmail.com> wrote:
> Hi,
>
> remembering that I had volunteered to contribute to documentation,
> I've had a brief off-list exchange with Casey about this.
> Interestingly, we both have in common that we like to have reasonably
> sized work items that can be ticked off in predictable time frames.
> Probably more people feel like this.
>
> The questions you ask, and the solutions you propose make sense to me.

OK, fine.

> On Wed, Aug 25, 2010 at 8:20 AM, Hannes Hirzel <hannes.hirzel at gmail.com>
> wrote:
>> 1) How do we include the help of people with maybe time as little as 1
>> hour per month (but who have a huge Smalltalk knowhow, e.g. R.J.)
>>
>> 2) Where should we start?
>>
>> My answers
>> 1) Have two persons who have commit access to the trunk who the other
>> commiters trust who will commit changes. It is very motivating if I
>> write a class comment for example and one day later it is in all my
>> trunk images I update.
>
> Why two? Class comments and documentation are trunk code, so trunk
> developers should be able and entitled to contribute them. Everyone
> interested can contribute via the inbox.

OK, thank you for reminding us of this.
You are right,
nobody holds us back approaching one of the commiters we see active
and ask him to commit a 'class comment' only change for us.


> I think that the more complicated task is to get started (your
> question 2). What needs to be documented? Who does it? How can this be
> organised in an unobtrusive way?
>
> What? - See below.
> Who? - All of us.
> How? - See below.
>
>> 2a) I would say it should be customer driven. We should go to the
>> beginners list and ask them what they want to know and try to work
>> there.
>> 2b) I did some querying about which classes need comments. More
>> information available on request.
>
> Mantis, Mantis, Mantis. Documentation issues should be considered
> "bugs" (in the sense that they bug people).

I think this is the key
  "Missing documentation is a defect / bug".


 Requests for documentation
> improvements / additions could be posted in a dedicated bug category.

We have to check if  there a is a  category for tag a ticket as
'Documentation' in Mantis?
If not we have to get it included there.


> I would expect particularly class comment issues to be about the size
> that I alluded to above (reasonably sized, tickable-off in predictable
> time - say, an hour a week, as you mentioned).
>
> How about asking people to submit requests for documentation via
> Mantis? Point people on the newbies list to that and have them ask for
> improvement.

I second this idea.

>
> How about turning your "more information" into some Mantis issues right
> away?

Fine, thank you for the suggestion. I will file tickets in the
upcoming weeks if people agree that we should go this road for
documentation requests.

To summarize: We have to get documentation tasks into "chewable
chunks". We have to work "customer oriented". This means to do things
real people actually using Squeak 4.1 want to know.


Best wishes

Hannes