discovering public repository items?

> -----Original Message-----
> From: Mark D. Roberts [mailto:[hidden email]]
> Sent: Tuesday, July 18, 2006 7:51 AM
> To: Andrea Gammachi; VWNC
> Subject: Re: discovering public repository items?
>
> Andrea,
>
> At 04:54 PM 7/18/2006, Andrea Gammachi wrote:
> >hello. i've been browsing the Published Items but was unable to found a
> >descriptive text for many packages (ASN, WSDL, TestBundle, SLesson, LAN,
> >Grocery, CS2Soap, WaveDev, ... many others) so i'd like to know if i must
> >to install or browse something else (an URL?) in order to see what an
> item
> >installs.
>
> Currently, there is no other information available. You can try loading
> things and provided you land on the right entry point, you may not get too
> many errors during loading, and then you can see if there are any class
> comments for the parts that did load.
>
> We have a forthcoming project called SmalltalkDoc which is intended to
> provide a web interface to the contents of the repository, but it can't
> conjure up missing descriptions for components.
>
> >is there a HOW-TO for publishing packages (i mean the right way :)?
>
> The "Source Code Management Guide" PDF in the /doc directory contains
> probably more than you want to know about Store, packages, and strategies
> for publishing.
>
> For guidelines on writing the descriptive text attached to your own
> packages, you might find this useful:
>
> http://www.cincomsmalltalk.com/CincomSmalltalkWiki/Documentation+Standards
> +Proposal
>
> HTH,
>
> M. Roberts
> Cincom Systems, Inc.

>So, how do we manage it before it becomes unwieldly?
>
>Terry
>
>===========================================================
>Terry Raymond       Smalltalk Professional Debug Package
>Crafted Smalltalk
>80 Lazywood Ln.
>Tiverton, RI  02878
>(401) 624-4517      [hidden email]
><http://www.craftedsmalltalk.com>
>===========================================================
>> -----Original Message-----
>> From: Mark D. Roberts [mailto:[hidden email]]
>> Sent: Tuesday, July 18, 2006 7:51 AM
>> To: Andrea Gammachi; VWNC
>> Subject: Re: discovering public repository items?
>>
>> Andrea,
>>
>> At 04:54 PM 7/18/2006, Andrea Gammachi wrote:
>> >hello. i've been browsing the Published Items but was unable to found a
>> >descriptive text for many packages (ASN, WSDL, TestBundle, SLesson, LAN,
>> >Grocery, CS2Soap, WaveDev, ... many others) so i'd like to know if i must
>> >to install or browse something else (an URL?) in order to see what an
>> item
>> >installs.
>>
>> Currently, there is no other information available. You can try loading
>> things and provided you land on the right entry point, you may not get too
>> many errors during loading, and then you can see if there are any class
>> comments for the parts that did load.
>>
>> We have a forthcoming project called SmalltalkDoc which is intended to
>> provide a web interface to the contents of the repository, but it can't
>> conjure up missing descriptions for components.
>>
>> >is there a HOW-TO for publishing packages (i mean the right way :)?
>>
>> The "Source Code Management Guide" PDF in the /doc directory contains
>> probably more than you want to know about Store, packages, and strategies
>> for publishing.
>>
>> For guidelines on writing the descriptive text attached to your own
>> packages, you might find this useful:
>>
>> http://www.cincomsmalltalk.com/CincomSmalltalkWiki/Documentation+Standards
>> +Proposal
>>
>> HTH,
>>
>> M. Roberts
>> Cincom Systems, Inc.

>So, how do we manage it before it becomes unwieldly?
>
>Terry
>
>===========================================================
>Terry Raymond       Smalltalk Professional Debug Package
>Crafted Smalltalk
>80 Lazywood Ln.
>Tiverton, RI  02878
>(401) 624-4517      [hidden email]
><http://www.craftedsmalltalk.com>
>===========================================================
> > -----Original Message-----
> > From: Mark D. Roberts [mailto:[hidden email]]
> > Sent: Tuesday, July 18, 2006 7:51 AM
> > To: Andrea Gammachi; VWNC
> > Subject: Re: discovering public repository items?
> >
> > Andrea,
> >
> > At 04:54 PM 7/18/2006, Andrea Gammachi wrote:
> > >hello. i've been browsing the Published Items but was unable to found a
> > >descriptive text for many packages (ASN, WSDL, TestBundle, SLesson, LAN,
> > >Grocery, CS2Soap, WaveDev, ... many others) so i'd like to know if i must
> > >to install or browse something else (an URL?) in order to see what an
> > item
> > >installs.
> >
> > Currently, there is no other information available. You can try loading
> > things and provided you land on the right entry point, you may not get too
> > many errors during loading, and then you can see if there are any class
> > comments for the parts that did load.
> >
> > We have a forthcoming project called SmalltalkDoc which is intended to
> > provide a web interface to the contents of the repository, but it can't
> > conjure up missing descriptions for components.
> >
> > >is there a HOW-TO for publishing packages (i mean the right way :)?
> >
> > The "Source Code Management Guide" PDF in the /doc directory contains
> > probably more than you want to know about Store, packages, and strategies
> > for publishing.
> >
> > For guidelines on writing the descriptive text attached to your own
> > packages, you might find this useful:
> >
> > http://www.cincomsmalltalk.com/CincomSmalltalkWiki/Documentation+Standards
> > +Proposal
> >
> > HTH,
> >
> > M. Roberts
> > Cincom Systems, Inc.

> At 09:54 PM 7/18/2006, Terry Raymond wrote:
>> I suppose we need to also consider annotating the packages
>> and bundles to indicate what VW version they apply to.
>
> SmalltalkDoc includes annotations for that.
>
>> Additionally, I suspect it would be helpful to remove
>> obsolete items.
>
> There is a way to do that with Store, but somebody needs to decide which
> items can go.
>
> M
>
>
>> So, how do we manage it before it becomes unwieldly?
>>
>> Terry
>>
>> ===========================================================
>> Terry Raymond       Smalltalk Professional Debug Package
>> Crafted Smalltalk
>> 80 Lazywood Ln.
>> Tiverton, RI  02878
>> (401) 624-4517      [hidden email]
>> <http://www.craftedsmalltalk.com>
>> ===========================================================
>> > -----Original Message-----
>> > From: Mark D. Roberts [mailto:[hidden email]]
>> > Sent: Tuesday, July 18, 2006 7:51 AM
>> > To: Andrea Gammachi; VWNC
>> > Subject: Re: discovering public repository items?
>> >
>> > Andrea,
>> >
>> > At 04:54 PM 7/18/2006, Andrea Gammachi wrote:
>> > >hello. i've been browsing the Published Items but was unable to
>> found a
>> > >descriptive text for many packages (ASN, WSDL, TestBundle, SLesson,
>> LAN,
>> > >Grocery, CS2Soap, WaveDev, ... many others) so i'd like to know if
>> i must
>> > >to install or browse something else (an URL?) in order to see what an
>> > item
>> > >installs.
>> >
>> > Currently, there is no other information available. You can try loading
>> > things and provided you land on the right entry point, you may not
>> get too
>> > many errors during loading, and then you can see if there are any class
>> > comments for the parts that did load.
>> >
>> > We have a forthcoming project called SmalltalkDoc which is intended to
>> > provide a web interface to the contents of the repository, but it can't
>> > conjure up missing descriptions for components.
>> >
>> > >is there a HOW-TO for publishing packages (i mean the right way :)?
>> >
>> > The "Source Code Management Guide" PDF in the /doc directory contains
>> > probably more than you want to know about Store, packages, and
>> strategies
>> > for publishing.
>> >
>> > For guidelines on writing the descriptive text attached to your own
>> > packages, you might find this useful:
>> >
>> >
>> http://www.cincomsmalltalk.com/CincomSmalltalkWiki/Documentation+Standards 
>>
>> > +Proposal
>> >
>> > HTH,
>> >
>> > M. Roberts
>> > Cincom Systems, Inc.
>
>

> -----Original Message-----
> From: Dave Stevenson [mailto:[hidden email]]
> Sent: Tuesday, July 18, 2006 2:32 PM
> To: 'VWNC'
> Subject: Re: discovering public repository items?
>
>  >> Additionally, I suspect it would be helpful to remove obsolete items.
>
>  > There is a way to do that with Store, but somebody needs to decide
> which items can go.
>
> I agree with Alan about not removing items.  What may be obsolete for
> the current environment may still have value for older environments.
> Even in current environments an item may be useful as example code.
> What we need is not less clutter in the repository itself, but better
> tools for filtering the clutter based on more than just the name.
>
> I think we need to ensure that 'obsolete' does not obscure the
> usefulness of the code for older versions.  'obsolete' is really a
> valuation of the usefulness of an item in the context of the current
> environment.  I think a better approach might be to annotate versions
> for which something has been known to work.  If the latest compatable
> version is 5i.4, that should raise a big warning in the mind of anyone
> looking for current stuff.  But for those looking for stuff for 5i.4,
> 'obsolete' won't get in the way.
>
> For example, ForkedUI was 'obsoleted' by MultiProcUI.  It is more useful
> to mark ForkedUI as compatable with certain versions (and maybe also
> explicitly mark it as incompatable for version Y and later) than to just
> mark it 'obsolete'.
>
> While I'm at it, this reminds me of my biggest peeve with "blessing
> levels", namely that they improperly mix incompatable metrics.
> BasicBlessingPolicy offers the following:
> 'Broken'
> 'Work In Progress'
> 'Development'
> 'To Review'
> 'Patch'
> 'Integration-Ready'
> 'Integrated'
> 'Ready to Merge'
> 'Merged'
> 'Tested'
> 'Internal Release'
> 'Released'
>
> This is a mixed bag of several metrics, such as:
> Quality:
> 'Broken'
> 'Work In Progress'
> 'Tested'
>
> Distribution:
> 'Development'
> 'Patch'
> 'Internal Release'
> 'Released'
>
> Misc. State of Development Process:
> 'To Review'
> 'Integration-Ready'
> 'Integrated'
> 'Ready to Merge'
> 'Merged'
> 'Tested'
>
> This is a very shallow attempt at categorizing these, but it serves to
> illustrate the point.  To truly capture and retain the usefulness of
> these categories of information, the current "blessing level" really
> needs to be split into its various not-very-related parts.
>
> Dave
>
> Mark D. Roberts wrote:
> > At 09:54 PM 7/18/2006, Terry Raymond wrote:
> >> I suppose we need to also consider annotating the packages
> >> and bundles to indicate what VW version they apply to.
> >
> > SmalltalkDoc includes annotations for that.
> >
> >> Additionally, I suspect it would be helpful to remove
> >> obsolete items.
> >
> > There is a way to do that with Store, but somebody needs to decide which
> > items can go.
> >
> > M
> >
> >
> >> So, how do we manage it before it becomes unwieldly?
> >>
> >> Terry
> >>
> >> ===========================================================
> >> Terry Raymond       Smalltalk Professional Debug Package
> >> Crafted Smalltalk
> >> 80 Lazywood Ln.
> >> Tiverton, RI  02878
> >> (401) 624-4517      [hidden email]
> >> <http://www.craftedsmalltalk.com>
> >> ===========================================================
> >> > -----Original Message-----
> >> > From: Mark D. Roberts [mailto:[hidden email]]
> >> > Sent: Tuesday, July 18, 2006 7:51 AM
> >> > To: Andrea Gammachi; VWNC
> >> > Subject: Re: discovering public repository items?
> >> >
> >> > Andrea,
> >> >
> >> > At 04:54 PM 7/18/2006, Andrea Gammachi wrote:
> >> > >hello. i've been browsing the Published Items but was unable to
> >> found a
> >> > >descriptive text for many packages (ASN, WSDL, TestBundle, SLesson,
> >> LAN,
> >> > >Grocery, CS2Soap, WaveDev, ... many others) so i'd like to know if
> >> i must
> >> > >to install or browse something else (an URL?) in order to see what
> an
> >> > item
> >> > >installs.
> >> >
> >> > Currently, there is no other information available. You can try
> loading
> >> > things and provided you land on the right entry point, you may not
> >> get too
> >> > many errors during loading, and then you can see if there are any
> class
> >> > comments for the parts that did load.
> >> >
> >> > We have a forthcoming project called SmalltalkDoc which is intended
> to
> >> > provide a web interface to the contents of the repository, but it
> can't
> >> > conjure up missing descriptions for components.
> >> >
> >> > >is there a HOW-TO for publishing packages (i mean the right way :)?
> >> >
> >> > The "Source Code Management Guide" PDF in the /doc directory contains
> >> > probably more than you want to know about Store, packages, and
> >> strategies
> >> > for publishing.
> >> >
> >> > For guidelines on writing the descriptive text attached to your own
> >> > packages, you might find this useful:
> >> >
> >> >
> >>
> http://www.cincomsmalltalk.com/CincomSmalltalkWiki/Documentation+Standards
> >>
> >> > +Proposal
> >> >
> >> > HTH,
> >> >
> >> > M. Roberts
> >> > Cincom Systems, Inc.
> >
> >

> Terry Raymond wrote:
>> Dave
>>
>> I pretty much agree with you. I think the items need
>> a tag indicating which versions they are known to work
>> with and they need a meaningful title or description.
>> The title or description really does not need to be as
>> extensive as some package comments are.
>>
>> Now, who is going to do it?
>
> SqueakMap attempts to do much of what has been discussed here. Looking
> at SqueakMap and figuring out its strong and weak points would be a
> useful thing to do for anyone thinking of attacking this problem.
>
> If the licenses are compatible, we might be able to reuse some portion
> of the SqueakMap code.
>
> Check out http://map.squeak.org/ -- the interface from within Squeak is
> nicer than the web interface, but you can see all of the package info on
> the web.
>
> -Martin
>

>Well, as Mark mentioned SmalltalkDoc is already underway.  Wouldn't
>it make more sense to begin using that?
>
>Dave
>
>Martin McClure wrote:
>>Terry Raymond wrote:
>>>Dave
>>>
>>>I pretty much agree with you. I think the items need
>>>a tag indicating which versions they are known to work
>>>with and they need a meaningful title or description.
>>>The title or description really does not need to be as
>>>extensive as some package comments are.
>>>
>>>Now, who is going to do it?
>>SqueakMap attempts to do much of what has been discussed here.
>>Looking at SqueakMap and figuring out its strong and weak points
>>would be a useful thing to do for anyone thinking of attacking this problem.
>>If the licenses are compatible, we might be able to reuse some
>>portion of the SqueakMap code.
>>Check out http://map.squeak.org/ -- the interface from within
>>Squeak is nicer than the web interface, but you can see all of the
>>package info on the web.
>>-Martin

> SmalltalkDoc doesn't solve the problem.  Heck, you could solve a large
> part of it if people put in Package/Bundle comments when they published
> - if they won't do that, I seriously doubt that they'll go wild over
> more doc opportunities :)
>
>
> At 06:41 PM 7/18/2006, you wrote:
>> Well, as Mark mentioned SmalltalkDoc is already underway.  Wouldn't it
>> make more sense to begin using that?
>>
>> Dave
>>
>> Martin McClure wrote:
>>> Terry Raymond wrote:
>>>> Dave
>>>>
>>>> I pretty much agree with you. I think the items need
>>>> a tag indicating which versions they are known to work
>>>> with and they need a meaningful title or description.
>>>> The title or description really does not need to be as
>>>> extensive as some package comments are.
>>>>
>>>> Now, who is going to do it?
>>> SqueakMap attempts to do much of what has been discussed here.
>>> Looking at SqueakMap and figuring out its strong and weak points
>>> would be a useful thing to do for anyone thinking of attacking this
>>> problem.
>>> If the licenses are compatible, we might be able to reuse some
>>> portion of the SqueakMap code.
>>> Check out http://map.squeak.org/ -- the interface from within Squeak
>>> is nicer than the web interface, but you can see all of the package
>>> info on the web.
>>> -Martin
>
> <Talk Small and Carry a Big Class Library>
> James Robertson, Product Manager, Cincom Smalltalk
> http://www.cincomsmalltalk.com/blog/blogView
>
>

> At 03:44 AM 7/19/2006, Terry Raymond wrote:
>> I pretty much agree with you. I think the items need
>> a tag indicating which versions they are known to work
>> with and they need a meaningful title or description.
>
> Why not use prerequisites? Surely it's better to improve those, rather
> than add another mechanism. Think about the following:
>
> * How do we know what VW version we are in? The VM's id is not the right
> answer, since a 7.0 image could be used with the 7.4.1 VM.
> SystemUtils.SystemVersionName has only been around since 7.2, so
> wouldn't work for older versions, and is just a string set manually.
>
> * Dependencies are rarely on a VW version per se, but on some feature
> provided by some VW component. E.g. we quite often have a newer version
> of the XML and WebServices stuff loaded, because we require corrections
> or new features
>
> * If the current prerequisite mechanism doesn't work nicely for
> specifying the most basic of requirements, a VW version, it probably has
> problems specifying prerequisites in other cases too. Improving it to
> specify VW versions will improve it for other prerequisite cases.
>
> * Packages are the primary code components, and already have a
> versioning mechanism. The base visual.im contains versioning info for at
> least all bundles. Cincom recommends publishing the base, and that would
> be helped greatly if we all had the same version names - effectively
> replicating a given version from the Cincom bear73 repository to our
> local repositories.
>
> * Good examples of prerequisite mechanisms that exist in other systems,
> e.g. Linux package loaders, use the same mechanism for specifying a
> dependency on a "system version" as for a dependency on the smallest
> component's version.
>
> Note that I'm not saying this is an easy problem, quite the opposite.
> But it does seem to be something that needs solving, and adding another
> hack solution isn't going to help.
>
> Very roughly, I think as a minimum a prerequisite should be able to
> specify a specific minimum and maximum package version. Normally, you'd
> just specify the minimum version, and then that version or any
> *descendant* would be legal. Note the difference from Store's broken
> "load latest version" - that works fine until there is a branch, e.g.
> publishing a fix to an old version.
>
> Steve
>
>

> SmalltalkDoc doesn't solve the problem.  Heck, you could solve a large
> part of it if people put in Package/Bundle comments when they
> published - if they won't do that, I seriously doubt that they'll go
> wild over more doc opportunities :)
>
>
> At 06:41 PM 7/18/2006, you wrote:
>> Well, as Mark mentioned SmalltalkDoc is already underway.  Wouldn't
>> it make more sense to begin using that?
>>
>> Dave
>>
>> Martin McClure wrote:
>>> Terry Raymond wrote:
>>>> Dave
>>>>
>>>> I pretty much agree with you. I think the items need
>>>> a tag indicating which versions they are known to work
>>>> with and they need a meaningful title or description.
>>>> The title or description really does not need to be as
>>>> extensive as some package comments are.
>>>>
>>>> Now, who is going to do it?
>>> SqueakMap attempts to do much of what has been discussed here.
>>> Looking at SqueakMap and figuring out its strong and weak points
>>> would be a useful thing to do for anyone thinking of attacking this
>>> problem.
>>> If the licenses are compatible, we might be able to reuse some
>>> portion of the SqueakMap code.
>>> Check out http://map.squeak.org/ -- the interface from within Squeak
>>> is nicer than the web interface, but you can see all of the package
>>> info on the web.
>>> -Martin
>
> <Talk Small and Carry a Big Class Library>
> James Robertson, Product Manager, Cincom Smalltalk
> http://www.cincomsmalltalk.com/blog/blogView
>
>

>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

>At 08:41 PM 7/19/2006, you wrote:
>>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
>
><Talk Small and Carry a Big Class Library>
>James Robertson, Product Manager, Cincom Smalltalk
>http://www.cincomsmalltalk.com/blog/blogView
>