Re: enreaching raw code [was Re: discovering public repository items?]

> Jaroslaw,
>
> At 06:59 AM 7/20/2006, Jaroslaw Podgajny wrote:
> >The question is what can be done to make it more natural to put comments
> >in all beneficial places. If there was a way to make people see the
> >benefits of writing the comments straightaway or somehow make it part of
> >the development cycle things could look different.
> >I have a similar feel that adding more ways of commenting code will not
> >work. Forcing constrains around it won't work either. It has to be
> >integrated into environment and "make sense to write them" for the idea to
> >pick up.
>
> After looking at this problem for several years, my conclusion is that
> there is an underlying cultural dimension that is separate from the tools
> issue, and this now seems to me more decisive. For whatever reason,
> Smalltalkers just tend not to write comments. In other programming
> communities, comments are considered part of the development process. In
> ours, they are not. Smalltalkers have various excuses for why comments are
> not necessary, which eventually conflict with the needs of somebody trying
> to learn Smalltalk or re-use some existing code. In the larger scheme of
> things, the lack of comments serves to isolate us from the rest of the
> world.
>
> This thread started because somebody was looking in the public repository,
> found no comments for the code components published there, and then (very
> charitably) wondered if the comments were to be found somewhere else. The
> answer was "no" and this is where the rubber hits the road. Then, we
> started talking about ways to improve the situation.
>
> While I agree that we can and should improve the tools, the pay-off is
> likely to be small. As Jim pointed out, if people won't use the existing
> mechanisms they likely won't suddenly start making extensive use of any new
> tool options. We can get some improvement, we need to improve the tools, we
> need to be realistic about the outcome.
>
> So, we might also consider "social" solutions to this problem. Right now,
> nobody is in charge of the public store and the burden falls upon each user
> to decide what each component does, what works, what doesn't, what's
> released, what's obsolete, etc. There are no conventions, no rules. If
> somebody were in charge of the repository and they could act as an editor,
> marking some things obsolete, nagging developers about comments, etc., it
> would help to improve the new-user experience. The tools also need to be
> improved, Store is deficient in this regard, but if we really care about
> making the public repository accessible to new developers, then I think we
> need to do both.
>
> Imagine that we were all journalists working for a newspaper called "The
> Public Store Times". We write articles, and through the miracle of modern
> technology, we publish them ourselves. Yet, we have no editor in charge of
> our newspaper, and we have no editorial standards. Each journalist has
> his/her own idea about what at article looks like. Sometimes, occasionally,
> new people read our newspaper and say "Your newspaper is kind of tedious to
> read -- how about including a little summary before each article?". At this
> point, we might discuss editorial standards -- "What should an article look
> like? How should it be organized? Should it have a one-line summary? Should
> we refuse to release it until it does? Etc." We might discuss an editorial
> function, i.e., "Should we try to get an editor in charge of this?".
> Finally, we might discuss tools, i.e., "How can we improve our tools so
> that it is easier to write good articles?".
>
> This last discussion about tools is what we always have, but clearly this
> is not enough. We could improve our tools 200% but some journalists still
> won't use them. In lieu of new policies and somebody to enforce them, or in
> lieu of a collective decision to suddenly change the way we write articles,
> the quality of our newspaper probably won't improve much.
>
> This is a half-hearted analogy, but the point is clear enough. Since we do
> not collectively think it is important to communicate with new users, e.g.
> by making our repository legible to them, we haven't really discussed
> editorial standards or an editorial function (somebody "in charge").
>
> If we decide that we care about making the public store more legible to new
> developers, we might do the following:
>
>          -- Institute a policy that any code marked as "released" must have
> adequate package/bundle comments
>          -- Decide on a simple definition of an "adequate" comment
>          -- Put an administrator in charge of the repository who can change
> blessings on components, e.g., demoting anything that is blessed as
> "released" which lacks comments
>          -- Fix the Published Items tool to include a "blessing filter" so
> that by default in VisualWorks NC, it only shows released components. The
> filter can be twiddled easily, of course.
>          -- Improve the IDE tools for adding comments, perhaps along the
> lines of SmalltalkDoc
>          -- Add a web interface for displaying the contents of the
> repository, again, along the lines of SmalltalkDoc
>
> If we did all of these things, it would dramatically improve the noob
> user-experience with Store. It would make it easier for new developers to
> join us, i.e., to grow our community.
>
> >The problem is similar to the issue of maintainability of a help system -
> >it is not a challenge to create one. How to make it not become patchy or
> >deteriorates over time is the big deal.
> >
> >We have a demand for a good help system but not much thoughts went into it
> >yet Some wild ideas were going in the direction of integrated wiki/blog
> >things... Any ideas welcome.
>
> This point is tangential to the thread, but by chance I have done some work
> on the VisualWorks Help System and my experience has been similar to yours.
> The problems are in authoring content and maintaining the system and the
> content. The VW Help system was a prototype, there have been no resources
> within Cincom to improve it since, and so it has deteriorated into its
> current state of decrepitude. Since VisualWorks lacked basic UI features
> like a hypertext widget, we had to build the VW Help browser using a
> third-party package from Arbor. This package came with no documentation,
> inadequate comments (sound familiar?) and it is now unmaintainable junk. We
> want to throw it out but, five years later, VisualWorks still doesn't have
> any support for hypertext.
>
>  From here, there are roughly two directions ahead. One is that we build
> hypertext support into VisualWorks and write a new Help Browser. The other
> is that we punt completely on the idea of integrated Help, admit to
> ourselves that VisualWorks isn't up to the job of building a Help Browser,
> and just use an external web browser. The problem with the latter direction
> is that we lose the ability to click on something in the Help browser and,
> for example, open a Workspace or load a parcel into VisualWorks. We lose
> the ability to search the content. Also, and more significantly, all modern
> IDEs are now moving towards integrated Help/Documentation. Eclipse, for
> example, has this. The facility for help/documentation/tutorials in Eclipse
> is now years ahead of VisualWorks and the gap is only going to grow wider.
> This translates into a direct impact on the noob experience, and IMHO
> Eclipse now offers a superior noob experience. We can argue all we want
> about the weaknesses of the underlying language, we can argue all we want
> about the design of the Eclipse IDE, we can be the Sony Beta to Eclipse's
> VHS, but Eclipse offers a smoother noob experience.
>
> The other direction would be to build a new Help Browser and push for
> greater integration of tools/help/doc inside VisualWorks. This means we
> need to solve the long-standing problem of hypertext. Fortunately, the
> situation has changed since we built the prototype Help Browser. There is
> now a real XML display subsystem called WithStyle. It also includes an XML
> editor. It would not be difficult to build a new Help System using
> WithStyle. In fact, I made a small prototype to see how it would work. It
> is not difficult to read the existing Help content and translate it into
> structured XML, I have tried that too. The difficulty is getting WithStyle
> more properly integrated into VisualWorks, and finding the cycles to do all
> the editorial work to update the content and get it into order. I can't do
> that now.
>
> If you are interested in talking about this second direction, feel free to
> e-mail me directly.
>
> Cheers,
>
> M. Roberts

> Jaroslaw,
>
> At 06:59 AM 7/20/2006, Jaroslaw Podgajny wrote:
> >The question is what can be done to make it more natural to put
> >comments in all beneficial places. If there was a way to make people
> >see the benefits of writing the comments straightaway or somehow make
> >it part of the development cycle things could look different.
> >I have a similar feel that adding more ways of commenting code will
> >not work. Forcing constrains around it won't work either. It has to
> >be integrated into environment and "make sense to write them" for the
> >idea to pick up.
>
> After looking at this problem for several years, my conclusion is that
> there is an underlying cultural dimension that is separate from the
> tools issue, and this now seems to me more decisive. For whatever
> reason, Smalltalkers just tend not to write comments. In other
> programming communities, comments are considered part of the
> development process. In ours, they are not. Smalltalkers have various
> excuses for why comments are not necessary, which eventually conflict
> with the needs of somebody trying to learn Smalltalk or re-use some
> existing code. In the larger scheme of things, the lack of comments
> serves to isolate us from the rest of the world.
>
> This thread started because somebody was looking in the public
> repository, found no comments for the code components published there,
> and then (very
> charitably) wondered if the comments were to be found somewhere else.
> The answer was "no" and this is where the rubber hits the road. Then,
> we started talking about ways to improve the situation.
>
> While I agree that we can and should improve the tools, the pay-off is
> likely to be small. As Jim pointed out, if people won't use the
> existing mechanisms they likely won't suddenly start making extensive
> use of any new tool options. We can get some improvement, we need to
> improve the tools, we need to be realistic about the outcome.
>
> So, we might also consider "social" solutions to this problem. Right
> now, nobody is in charge of the public store and the burden falls upon
> each user to decide what each component does, what works, what
> doesn't, what's released, what's obsolete, etc. There are no
> conventions, no rules. If somebody were in charge of the repository
> and they could act as an editor, marking some things obsolete, nagging
> developers about comments, etc., it would help to improve the new-user
> experience. The tools also need to be improved, Store is deficient in
> this regard, but if we really care about making the public repository
> accessible to new developers, then I think we need to do both.
>
> Imagine that we were all journalists working for a newspaper called
> "The Public Store Times". We write articles, and through the miracle
> of modern technology, we publish them ourselves. Yet, we have no
> editor in charge of our newspaper, and we have no editorial standards.
> Each journalist has his/her own idea about what at article looks like.
> Sometimes, occasionally, new people read our newspaper and say "Your
> newspaper is kind of tedious to read -- how about including a little
> summary before each article?". At this point, we might discuss
> editorial standards -- "What should an article look like? How should
> it be organized? Should it have a one-line summary? Should we refuse
> to release it until it does? Etc." We might discuss an editorial function, i.e., "Should we try to get an editor in charge of this?".
> Finally, we might discuss tools, i.e., "How can we improve our tools
> so that it is easier to write good articles?".
>
> This last discussion about tools is what we always have, but clearly
> this is not enough. We could improve our tools 200% but some
> journalists still won't use them. In lieu of new policies and somebody
> to enforce them, or in lieu of a collective decision to suddenly
> change the way we write articles, the quality of our newspaper probably won't improve much.
>
> This is a half-hearted analogy, but the point is clear enough. Since
> we do not collectively think it is important to communicate with new users, e.g.
> by making our repository legible to them, we haven't really discussed
> editorial standards or an editorial function (somebody "in charge").
>
> If we decide that we care about making the public store more legible
> to new developers, we might do the following:
>
>          -- Institute a policy that any code marked as "released" must
> have adequate package/bundle comments
>          -- Decide on a simple definition of an "adequate" comment
>          -- Put an administrator in charge of the repository who can
> change blessings on components, e.g., demoting anything that is
> blessed as "released" which lacks comments
>          -- Fix the Published Items tool to include a "blessing
> filter" so that by default in VisualWorks NC, it only shows released
> components. The filter can be twiddled easily, of course.
>          -- Improve the IDE tools for adding comments, perhaps along
> the lines of SmalltalkDoc
>          -- Add a web interface for displaying the contents of the
> repository, again, along the lines of SmalltalkDoc
>
> If we did all of these things, it would dramatically improve the noob
> user-experience with Store. It would make it easier for new developers
> to join us, i.e., to grow our community.
>
> >The problem is similar to the issue of maintainability of a help
> >system - it is not a challenge to create one. How to make it not
> >become patchy or deteriorates over time is the big deal.
> >
> >We have a demand for a good help system but not much thoughts went
> >into it yet Some wild ideas were going in the direction of integrated
> >wiki/blog things... Any ideas welcome.
>
> This point is tangential to the thread, but by chance I have done some
> work on the VisualWorks Help System and my experience has been similar to yours.
> The problems are in authoring content and maintaining the system and
> the content. The VW Help system was a prototype, there have been no
> resources within Cincom to improve it since, and so it has
> deteriorated into its current state of decrepitude. Since VisualWorks
> lacked basic UI features like a hypertext widget, we had to build the
> VW Help browser using a third-party package from Arbor. This package
> came with no documentation, inadequate comments (sound familiar?) and
> it is now unmaintainable junk. We want to throw it out but, five years
> later, VisualWorks still doesn't have any support for hypertext.
>
>  From here, there are roughly two directions ahead. One is that we
> build hypertext support into VisualWorks and write a new Help Browser.
> The other is that we punt completely on the idea of integrated Help,
> admit to ourselves that VisualWorks isn't up to the job of building a
> Help Browser, and just use an external web browser. The problem with
> the latter direction is that we lose the ability to click on something
> in the Help browser and, for example, open a Workspace or load a
> parcel into VisualWorks. We lose the ability to search the content.
> Also, and more significantly, all modern IDEs are now moving towards
> integrated Help/Documentation. Eclipse, for example, has this. The
> facility for help/documentation/tutorials in Eclipse is now years ahead of VisualWorks and the gap is only going to grow wider.
> This translates into a direct impact on the noob experience, and IMHO
> Eclipse now offers a superior noob experience. We can argue all we
> want about the weaknesses of the underlying language, we can argue all
> we want about the design of the Eclipse IDE, we can be the Sony Beta
> to Eclipse's VHS, but Eclipse offers a smoother noob experience.
>
> The other direction would be to build a new Help Browser and push for
> greater integration of tools/help/doc inside VisualWorks. This means
> we need to solve the long-standing problem of hypertext. Fortunately,
> the situation has changed since we built the prototype Help Browser.
> There is now a real XML display subsystem called WithStyle. It also
> includes an XML editor. It would not be difficult to build a new Help
> System using WithStyle. In fact, I made a small prototype to see how
> it would work. It is not difficult to read the existing Help content
> and translate it into structured XML, I have tried that too. The
> difficulty is getting WithStyle more properly integrated into
> VisualWorks, and finding the cycles to do all the editorial work to
> update the content and get it into order. I can't do that now.
>
> If you are interested in talking about this second direction, feel
> free to e-mail me directly.
>
> Cheers,
>
> M. Roberts

> 4 questions should be answered before I can really use the code:
> - what does it do (planing goals)
> - what to avoid when using, limitations
> - how does it do
> - how can I use it
>
> According to this 4 types of documentation would be necessary to make it easy in an ideal case:
>
> 1.) the planning (goals) documentation
> 2.) the developer's decision on the way to the implementation
> 3.) documentation about the result, i.e the implemented code
> 4.) tutorial-usage documentation with (lots of!) simple and real-life examples
>  

> -----Original Message-----
> From: nicolas cellier [mailto:[hidden email]]
> Sent: Thursday, July 20, 2006 3:20 AM
> To: [hidden email]
> Subject: Re: enreaching raw code [was Re: discovering public repository items?]
>
>
> IMHO, Smalltalkers are lazy because they think they write legible code.
> (more legible than C for example).
>
> However, I remember that st80 v2.3 and STV had quite good comments in delivered sources (this is less the case in all current ST dialects i know of).
>
> Knowing from other languages that comments are either false or at least not  up to date, ou philosophy may be  "the code is the better comments we have".
>
> Except we lack a good summary giving at least the entry points and some rationale discussing the implementation choices.
>
> It is clear that without comments, the store is unusable, not only for noob.
> I would like also Class name search, keyword search through the store.
>
> And yes, comments are maybe not enough (Cincom delivers tutorials in pdf
> format) and hyperlink is badly missing for online doc...
> Would Smalltalk from a web browser be the solution?
>
> Nicolas
>
> Le Jeudi 20 Juillet 2006 02:41, Mark D. Roberts a écrit :
>  
>> Jaroslaw,
>>
>> At 06:59 AM 7/20/2006, Jaroslaw Podgajny wrote:
>>    
>>> The question is what can be done to make it more natural to put
>>> comments in all beneficial places. If there was a way to make people
>>> see the benefits of writing the comments straightaway or somehow make
>>> it part of the development cycle things could look different.
>>> I have a similar feel that adding more ways of commenting code will
>>> not work. Forcing constrains around it won't work either. It has to
>>> be integrated into environment and "make sense to write them" for the
>>> idea to pick up.
>>>      
>> After looking at this problem for several years, my conclusion is that
>> there is an underlying cultural dimension that is separate from the
>> tools issue, and this now seems to me more decisive. For whatever
>> reason, Smalltalkers just tend not to write comments. In other
>> programming communities, comments are considered part of the
>> development process. In ours, they are not. Smalltalkers have various
>> excuses for why comments are not necessary, which eventually conflict
>> with the needs of somebody trying to learn Smalltalk or re-use some
>> existing code. In the larger scheme of things, the lack of comments
>> serves to isolate us from the rest of the world.
>>
>> This thread started because somebody was looking in the public
>> repository, found no comments for the code components published there,
>> and then (very
>> charitably) wondered if the comments were to be found somewhere else.
>> The answer was "no" and this is where the rubber hits the road. Then,
>> we started talking about ways to improve the situation.
>>
>> While I agree that we can and should improve the tools, the pay-off is
>> likely to be small. As Jim pointed out, if people won't use the
>> existing mechanisms they likely won't suddenly start making extensive
>> use of any new tool options. We can get some improvement, we need to
>> improve the tools, we need to be realistic about the outcome.
>>
>> So, we might also consider "social" solutions to this problem. Right
>> now, nobody is in charge of the public store and the burden falls upon
>> each user to decide what each component does, what works, what
>> doesn't, what's released, what's obsolete, etc. There are no
>> conventions, no rules. If somebody were in charge of the repository
>> and they could act as an editor, marking some things obsolete, nagging
>> developers about comments, etc., it would help to improve the new-user
>> experience. The tools also need to be improved, Store is deficient in
>> this regard, but if we really care about making the public repository
>> accessible to new developers, then I think we need to do both.
>>
>> Imagine that we were all journalists working for a newspaper called
>> "The Public Store Times". We write articles, and through the miracle
>> of modern technology, we publish them ourselves. Yet, we have no
>> editor in charge of our newspaper, and we have no editorial standards.
>> Each journalist has his/her own idea about what at article looks like.
>> Sometimes, occasionally, new people read our newspaper and say "Your
>> newspaper is kind of tedious to read -- how about including a little
>> summary before each article?". At this point, we might discuss
>> editorial standards -- "What should an article look like? How should
>> it be organized? Should it have a one-line summary? Should we refuse
>> to release it until it does? Etc." We might discuss an editorial function, i.e., "Should we try to get an editor in charge of this?".
>> Finally, we might discuss tools, i.e., "How can we improve our tools
>> so that it is easier to write good articles?".
>>
>> This last discussion about tools is what we always have, but clearly
>> this is not enough. We could improve our tools 200% but some
>> journalists still won't use them. In lieu of new policies and somebody
>> to enforce them, or in lieu of a collective decision to suddenly
>> change the way we write articles, the quality of our newspaper probably won't improve much.
>>
>> This is a half-hearted analogy, but the point is clear enough. Since
>> we do not collectively think it is important to communicate with new users, e.g.
>> by making our repository legible to them, we haven't really discussed
>> editorial standards or an editorial function (somebody "in charge").
>>
>> If we decide that we care about making the public store more legible
>> to new developers, we might do the following:
>>
>>          -- Institute a policy that any code marked as "released" must
>> have adequate package/bundle comments
>>          -- Decide on a simple definition of an "adequate" comment
>>          -- Put an administrator in charge of the repository who can
>> change blessings on components, e.g., demoting anything that is
>> blessed as "released" which lacks comments
>>          -- Fix the Published Items tool to include a "blessing
>> filter" so that by default in VisualWorks NC, it only shows released
>> components. The filter can be twiddled easily, of course.
>>          -- Improve the IDE tools for adding comments, perhaps along
>> the lines of SmalltalkDoc
>>          -- Add a web interface for displaying the contents of the
>> repository, again, along the lines of SmalltalkDoc
>>
>> If we did all of these things, it would dramatically improve the noob
>> user-experience with Store. It would make it easier for new developers
>> to join us, i.e., to grow our community.
>>
>>    
>>> The problem is similar to the issue of maintainability of a help
>>> system - it is not a challenge to create one. How to make it not
>>> become patchy or deteriorates over time is the big deal.
>>>
>>> We have a demand for a good help system but not much thoughts went
>>> into it yet Some wild ideas were going in the direction of integrated
>>> wiki/blog things... Any ideas welcome.
>>>      
>> This point is tangential to the thread, but by chance I have done some
>> work on the VisualWorks Help System and my experience has been similar to yours.
>> The problems are in authoring content and maintaining the system and
>> the content. The VW Help system was a prototype, there have been no
>> resources within Cincom to improve it since, and so it has
>> deteriorated into its current state of decrepitude. Since VisualWorks
>> lacked basic UI features like a hypertext widget, we had to build the
>> VW Help browser using a third-party package from Arbor. This package
>> came with no documentation, inadequate comments (sound familiar?) and
>> it is now unmaintainable junk. We want to throw it out but, five years
>> later, VisualWorks still doesn't have any support for hypertext.
>>
>>  From here, there are roughly two directions ahead. One is that we
>> build hypertext support into VisualWorks and write a new Help Browser.
>> The other is that we punt completely on the idea of integrated Help,
>> admit to ourselves that VisualWorks isn't up to the job of building a
>> Help Browser, and just use an external web browser. The problem with
>> the latter direction is that we lose the ability to click on something
>> in the Help browser and, for example, open a Workspace or load a
>> parcel into VisualWorks. We lose the ability to search the content.
>> Also, and more significantly, all modern IDEs are now moving towards
>> integrated Help/Documentation. Eclipse, for example, has this. The
>> facility for help/documentation/tutorials in Eclipse is now years ahead of VisualWorks and the gap is only going to grow wider.
>> This translates into a direct impact on the noob experience, and IMHO
>> Eclipse now offers a superior noob experience. We can argue all we
>> want about the weaknesses of the underlying language, we can argue all
>> we want about the design of the Eclipse IDE, we can be the Sony Beta
>> to Eclipse's VHS, but Eclipse offers a smoother noob experience.
>>
>> The other direction would be to build a new Help Browser and push for
>> greater integration of tools/help/doc inside VisualWorks. This means
>> we need to solve the long-standing problem of hypertext. Fortunately,
>> the situation has changed since we built the prototype Help Browser.
>> There is now a real XML display subsystem called WithStyle. It also
>> includes an XML editor. It would not be difficult to build a new Help
>> System using WithStyle. In fact, I made a small prototype to see how
>> it would work. It is not difficult to read the existing Help content
>> and translate it into structured XML, I have tried that too. The
>> difficulty is getting WithStyle more properly integrated into
>> VisualWorks, and finding the cycles to do all the editorial work to
>> update the content and get it into order. I can't do that now.
>>
>> If you are interested in talking about this second direction, feel
>> free to e-mail me directly.
>>
>> Cheers,
>>
>> M. Roberts
>>    
>
> -------------------------------------------------------
>
>
>