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

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Nicolas Cellier-3

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

-------------------------------------------------------

Reply | Threaded
Open this post in threaded view
|

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

Janos
 Hi,

perhaps my point of view is the other side of extremity, than the extreme... because it supposes you have time, time, time.

What is the purpose of the documentation/comments/tutorials?

To make it easy to understand what the code does.

What does it mean "understand"?

To build up a working "model" mentally which has the 1:1 mapping about the functionality, what I can use to make the existing code to operate and use to solve the task I have as a programmer (application programmer, supporter, developer). The more precise the mapping the better can I use the code.

As you see form this discussion (too) to build up this internal mental model the best way is not always a pioneer or discovery journey through the code itself.

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

But as always: because of the time limits and other constraints... this remains only a dream.

Janos




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

-------------------------------------------------------

Reply | Threaded
Open this post in threaded view
|

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

Jarek@GMX
Hi Janos,

Kazsoki, Janos wrote:
[...]

> 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
>  
I do agree with you that there are different types of comments but I
also believe that code should be self-explanatory. In most cases it is,
so I do not write comments myself often. I also rarely read them - only
if I do not understand the code I go back and check what the comment
says. The reasons for that many have already mentioned.

The comments I ignore are these which talk about what something does - I
can see that clearly from the code. The ones I love are these which talk
about why something took this form or another - these are the most
useful as it is not always clear why a number 8 is such a grate idea.
Now should these be taken out of a Smalltalk Browsers and shown on some
web page or in other form of documentation? I don't think so. I am not
sure anybody would want that.
Having a document containing package comments is a different thing.
Having it integrated inside a google-like search engine updated
frequently of the public repository is something I would really
appreciate. This is where I see reasons for links to tutorials, examples
etc.
The problem is that it is not obvious how to create such a beast so it
stays alive. Maybe the usual "start with something simple" is the way to go.
> But as always: because of the time limits and other constraints... this remains only a dream.
>  
I do not buy the lack of time as an excuse. In my opinion it only shows
that the underlying process is not appropriate for the cause. What is
the difference between writing comments and Unit Test? Both require
skill to choose the subject and define the scope and both have to be
incremental if they are going to work.



Regards, Jaroslaw.

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