Documentation Team

> Looking at
>
> http://squeak.org/Community/Teams/
>
> I don't see a documentation team listed. Has it been disbanded?
>
> If the documentation team has been disbanded, I would like to offer to
> lead a new documentation team (in which case I would draft up a proposal
> with expected deliverables, etc.) If the documentation team has not been
> disbanded, I would like to join it.

> Hi Casey,
>
> with all the documentation-related blurb I posted during campaigning,
> you got me started naturally. This is a very good idea. :-)
>
> What are your plans? What form of documentation do you envision, and
> what kind? How would you try to get people contribute documentation
> instead of just code? What do you think about making documentation
> available both in- and outside the image? Packageable?
>
> Sorry for the many questions, but this *is* an important topic IMHO,
> and I care. :-)
>
> Best,
>
> Michael
>
> On Mon, Apr 19, 2010 at 10:24 PM, Casey Ransberger
> <[hidden email]> wrote:
>> Looking at
>> http://squeak.org/Community/Teams/
>> I don't see a documentation team listed. Has it been disbanded?
>> If the documentation team has been disbanded, I would like to offer to
>> lead
>> a new documentation team (in which case I would draft up a proposal with
>> expected deliverables, etc.) If the documentation team has not been
>> disbanded, I would like to join it.
>
>

>
> Hello
>
> As we now have this nice help menu I think we should make use of it.
> New versions of the texts there may be easily put as an mcz file into
> the inbox and show up there for people connected to the trunk. So it
> will be under version control and considered to be a regular Squeak
> artifact. This is for the basic documentation including hooks and
> loading procedures.
>
> Additional documentation could be done in the form of some packages on
> Squeaksource which people may load on demand.
>
> A simple reader might be used for displaying the information.  A
> three-pane browser like
> http://lists.squeakfoundation.org/pipermail/beginners/attachments/20100419/0ea15bf9/PastedGraphic-1.png
>
> If somebody wants to go for immediate action: What about taking that
> and using it for displaying the Terse Guide of Squeak? Maybe somebody
> likes to put this into the inbox?
>
> I think documentation _in_ the image is important. The goal of
> documentation is to save time. If I for myself need several hours to
> find out a procedure, the next person does not need to have the same
> struggle. A few lines of text save ofther people a lot of struggle
>
> e.g. the installation of Pier2
> http://lists.squeakfoundation.org/pipermail/squeak-dev/2010-April/148974.html
>
>
> The nice thing people often forget is that any text may be selected
> and executed. This is something to really make use of.
> And: documentation should be loadable and unloadable like other modules.
>
> I am willing to contribute if meaningful transactions (of
> contributions) may be done within 30 minutes to 3 hours.
>
> Best wishes
>
> Hannes
>
> P.S.1 I think we should revive the documentation mailing list and have
> the discussion there to reduce the load on this list.
>
> P.S. 2
> Or the beginner's list might be a place as well for this as it is not
> crowded and there would be "customers".  The term 'beginner' might
> frighten some people who have been around for a long time. Anyhow if I
> do not know how something works in a particular area I am a beginner
> in that area. And the system is actually huge. In which other system
> are you allowed to tweak the GUI library for example.

> On 20.04.2010, at 17:25, Hannes Hirzel wrote:
>>
>> Hello
>>
>> As we now have this nice help menu I think we should make use of it.
>> New versions of the texts there may be easily put as an mcz file into
>> the inbox and show up there for people connected to the trunk. So it
>> will be under version control and considered to be a regular Squeak
>> artifact. This is for the basic documentation including hooks and
>> loading procedures.
>>
>> Additional documentation could be done in the form of some packages on
>> Squeaksource which people may load on demand.
>>
>> A simple reader might be used for displaying the information.  A
>> three-pane browser like
>> http://lists.squeakfoundation.org/pipermail/beginners/attachments/20100419/0ea15bf9/PastedGraphic-1.png
>>
>> If somebody wants to go for immediate action: What about taking that
>> and using it for displaying the Terse Guide of Squeak? Maybe somebody
>> likes to put this into the inbox?
>>
>> I think documentation _in_ the image is important. The goal of
>> documentation is to save time. If I for myself need several hours to
>> find out a procedure, the next person does not need to have the same
>> struggle. A few lines of text save ofther people a lot of struggle
>>
>> e.g. the installation of Pier2
>> http://lists.squeakfoundation.org/pipermail/squeak-dev/2010-April/148974.html
>>
>>
>> The nice thing people often forget is that any text may be selected
>> and executed. This is something to really make use of.
>> And: documentation should be loadable and unloadable like other modules.
>>
>> I am willing to contribute if meaningful transactions (of
>> contributions) may be done within 30 minutes to 3 hours.
>>
>> Best wishes
>>
>> Hannes
>>
>> P.S.1 I think we should revive the documentation mailing list and have
>> the discussion there to reduce the load on this list.
>>
>> P.S. 2
>> Or the beginner's list might be a place as well for this as it is not
>> crowded and there would be "customers".  The term 'beginner' might
>> frighten some people who have been around for a long time. Anyhow if I
>> do not know how something works in a particular area I am a beginner
>> in that area. And the system is actually huge. In which other system
>> are you allowed to tweak the GUI library for example.
>
> IMHO discussion of documentation should happen here on squeak-dev. It
> concerns everyone.
>
> The beginner's list is a place to get advice, not to discuss features or
> strategies.
>
> - Bert -
>
>
>
>

> Looking at
>
> http://squeak.org/Community/Teams/
>
> I don't see a documentation team listed. Has it been disbanded?
>
> If the documentation team has been disbanded, I would like to offer to lead
> a new documentation team (in which case I would draft up a proposal with
> expected deliverables, etc.) If the documentation team has not been
> disbanded, I would like to join it.

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

> On Wed, Aug 25, 2010 at 8:20 AM, Hannes Hirzel <[hidden email]>
> 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.

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

> On 4/19/10, Casey Ransberger <[hidden email]> wrote:
>> Looking at
>>
>> http://squeak.org/Community/Teams/
>>
>> I don't see a documentation team listed. Has it been disbanded?
>>
>> If the documentation team has been disbanded, I would like to offer to lead
>> a new documentation team (in which case I would draft up a proposal with
>> expected deliverables, etc.) If the documentation team has not been
>> disbanded, I would like to join it.
>
>
> Casey,
>
> you started this thread in April and there was quite some interest of
> people contributing but for lack of time or maybe lack of an
> appropriate approach only few things have happened. There are notable
> exceptions one. We have a help browser in the trunk by now and a good
> example of a documentation (Webclient) as well as one (1) tutorial
> about reading XML files.
>
> Jecel Assumpcao Jr. suggest that the should continue this effort
> http://lists.squeakfoundation.org/pipermail/squeak-dev/2010-August/152703.html.
>
> Casey Ransberger writes that he needs to find time.
>
>
> We are facing challenges here.
>
> 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.
>
> 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.
>
> --Hannes
>

> Hi,
>
> On Wed, Aug 25, 2010 at 4:33 PM, Casey Ransberger
> <[hidden email]> wrote:
>> I've had luck getting class comments in via inbox; the core devs seem quite happy to check documentation into the trunk.
>
> I'm a core dev myself for some reason, so there's really no major obstacle. :-)
>
> Best,
>
> Michael
>
>

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

> On 8/26/10, Casey Ransberger <[hidden email]> wrote:
> ....
>
> CURRENT ACTION FOCUS
>>
>> That said, I think the web facing docs are a lower priority than gettin some
>> good documentation written.
>>
> I agree with the priority setting. We need to produce more
> documentation _within_ the image.
>
> And as the tool to stay organised we have chosen Mantis.
>
> Generating a web version of it (something like Javadoc) - I am pretty
> sure we will find somebody to do it. Similar things have been done in
> the past.