On 8/25/10, Michael Haupt mhaupt@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@gmail.com wrote:
- 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.)
- Where should we start?
My answers
- 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