Education centre for Dolphin 5?

Do we have any sort of timeline for the completion of the Dolphin 5
documentation?


                            Steve

Steve,

> Do we have any sort of timeline for the completion of the Dolphin 5
> documentation?

Currently, we are struggling with the formatting of the help produced by the
Doc2Help documentation tool that we use. However, apart from one new section
on COM and some descriptions of the new tools (like the System Browser and
Flipper) the new documentation is pretty much like the old version 4 stuff.

If you want you can get a semblance of documentation and help by using the
old Dolphin 4 download. Go to the Dolphn 4 download library or use the
following link:

http://www.object-arts.com/Lib/Downloads/4.0/EducationCentre.msi

When opened this will prompt for the directory where Dolphin is installed.
Initially this will indicate a Dolphin 4 path so you should change it to the
location where Dolphin 5 is installed (usually C:\Program Files\Object
Arts\Dolphin Smalltalk 5.0). Once installed, start Dolphin and evaluate the
following in any workspace:

(RegKey localMachineRoot)
        at: (SessionManager current productRegistryKey , '\EducationCentre')
        put: (SessionManager current
installationDirectory,'\EducationCentre.chm::/htm/').

You should now be able to use the various Help menu items and F1 in the
various tools. Please note, though, that because this is the Dolphin 4 help
file, the screen shots will not be representative and there may well be
pages missing (like the help for Flipper for example). You should find that
it is better than nothing though.

Best Regards,

Andy Bower
Dolphin Support
http://www.object-arts.com
---
Are you trying too hard?
http://www.object-arts.com/Relax.htm
---

Andy Bower wrote:

> Currently, we are struggling with the formatting of the help produced by the
> Doc2Help documentation tool that we use. However, apart from one new section
> on COM and some descriptions of the new tools (like the System Browser and
> Flipper) the new documentation is pretty much like the old version 4 stuff.

Thanks for that. I am indeed using the D4 documentation as needed,
though I'm still looking forward to the D5 version, of course.

> Andy Bower



                           Steve

"Andy Bower" <[hidden email]> wrote
>
> > Do we have any sort of timeline for the completion of the Dolphin 5
> > documentation?
>
> Currently, we are struggling with the formatting of the help produced by
the
> Doc2Help documentation tool that we use. However, apart from one new
section
> on COM and some descriptions of the new tools (like the System Browser and
> Flipper) the new documentation is pretty much like the old version 4
stuff.

How unfortunate!  Andy, I noticed in my D.5 "tip of the day" that several
appear to be signed by Ian.  That brings to mind opening up your
documentation process to include volunteer help.  I think I am not alone in
saying that several of us customers would be happy to spend some time to
write improved documentation for some of the classes we understand.  That
would multiply the benefits for all customers as 90% of the classes are
currently not understood by me and perhaps others.

And yes I'm looking forward to documentation on the new Flipping Inspector.
I wrote some code that reads from a file which has a moderately standard
ascii zero as the terminal character it wasn't immediately obvious that was
the problem since the Flipper reports a single quote ' on the first page.

While I was on the ragged fringe of the Smalltalk movement since just before
the first OOPSLA, I was always skeptical of the self-documentation, terse
documentation, and no documentation object paradigm proposals.  Now I can
say for certian: "A well written method is worth a well written comment and
a well written class is worth a well written explination."

Sorry to fellow Oregonian Kent Beck, but expecting people to understand the
details of their own code after 3-6 months or immediately assimilate other's
code is extreme in any language, unless the application is so simple it
didn't really need coding. Some people had me convinced of eXtreme
Programming a few years ago on comp.lang.smalltalk with an example Singleton
sort I gave as a challenge.  But after seeing all the imperceivable code in
D.5 and reflecting on it in other Smalltalks, I reject the no comments leg
of the XP paradigm. Other parts of it may work well for those who use it,
but no comments will only work when AI is advanced enough to explain its own
code.  Otherwise it takes time to learn, interpret, and use other people's
code.  And that would be aided by well-written in depth documentation.

Kirk,

> How unfortunate!  Andy, I noticed in my D.5 "tip of the day" that several
> appear to be signed by Ian.  That brings to mind opening up your
> documentation process to include volunteer help.  I think I am not alone
in
> saying that several of us customers would be happy to spend some time to
> write improved documentation for some of the classes we understand.  That
> would multiply the benefits for all customers as 90% of the classes are
> currently not understood by me and perhaps others.

You may be right but there was a pattern section on the Wiki for some time,
with the idea that others could contribute to it but nothing ever
materialized. The contributors to this newsgroup, however, do sterling work
keeping the ship afloat. Of course, if anyone wants to submit well written
documentation sections or class comments then we'd be more than welcome to
receive them.

> While I was on the ragged fringe of the Smalltalk movement since just
before
> the first OOPSLA, I was always skeptical of the self-documentation, terse
> documentation, and no documentation object paradigm proposals.  Now I can
> say for certian: "A well written method is worth a well written comment
and
> a well written class is worth a well written explination."

I agree that class comments are more important since they can provide
overview information that generally can't be made available by other means.
They are also harder to write than method comments (a little rule I use is
that the harder a comment is to write, probably the more useful it is). IMO
most method comments are a waste of time.

> Sorry to fellow Oregonian Kent Beck, but expecting people to understand
the
> details of their own code after 3-6 months or immediately assimilate
other's
> code is extreme in any language, unless the application is so simple it
> didn't really need coding. Some people had me convinced of eXtreme
> Programming a few years ago on comp.lang.smalltalk with an example
Singleton
> sort I gave as a challenge.  But after seeing all the imperceivable code
in
> D.5 and reflecting on it in other Smalltalks, I reject the no comments leg
> of the XP paradigm. Other parts of it may work well for those who use it,
> but no comments will only work when AI is advanced enough to explain its
own
> code.  Otherwise it takes time to learn, interpret, and use other people's
> code.  And that would be aided by well-written in depth documentation.

Given my stance about method comments, I don't think anyone (including
myself and possibly even Beck) would disagree that having full help/printed
documentation/class comments/method comment *would* be desirable if there
was no associated cost.  However, the cost of this stuff is high; not just
in the writing but in the maintenance of it. It's like static typing..
sometimes it can be useful but the costs (in
writing/maintenance/flexibility)are just too onerous.

For example, each time we produce a new release of Dolphin the screendump
graphics in the online documentation need to be redone. Each time we do this
we vow to write a tool to automate the process (still more time expended).
Things get worse as the documentation gets lower towards the class and
method level. The Refactoring Browser knows nothing about the contents of
comments. If one changes a method or class name with the browser the
comments have to be searched out and edited manually (or using old fashioned
tools like grep). Maybe the RB should be enhanced to handle comments more
effectively but, again, that is still more effort.

As you've probably noticed, Dolphin is a very complex product and yet, in
the current marketplace all language tools are perceived as having a low
value (heck many people argue they should be free!). Couple this with the
niche market that Smalltalk is in and you can see the problem.

True, we could have a glossy Digitalk style manual*, full online help and
all class and method comments up to date. Having this, would inevitably slow
down the development process and the release of new versions. I would guess
that if all of this stuff was in place then we'd still be back with Dolphin
3. Fine, you say, if it means I can understand the product. However, that
would be two upgrade cycles lost to us and to maintain our meagre revenue I
would guess that Dolphin would have had to start of at 2-3x the price. I'm
pretty sure we would never have got off the ground if this were the case.
Would *you* have paid $1000 for Dolphin Pro?

* BTW, the glossy manual is meant to be easy to produce from the same Word
document files as the HTML help using this Doc2Help tool that we use. This
is far from true, however.

Best Regards,

Andy Bower
Dolphin Support
http://www.object-arts.com
---
Are you trying too hard?
http://www.object-arts.com/Relax.htm
---

"Andy Bower" <[hidden email]> wrote

> You may be right but there was a pattern section on the Wiki for some
time,
> with the idea that others could contribute to it but nothing ever
> materialized.

IMO, judging by the Patterns section at Powell's, the "world's biggest
bookstore" in Portland, which grew from zero to a few to a whole rack of
titles then dwindled down to a few again, I think Patterns is a fad that has
faded. People need real documentation or algorithm books, not Patterns.

>The contributors to this newsgroup, however, do sterling work
> keeping the ship afloat. Of course, if anyone wants to submit well written
> documentation sections or class comments then we'd be more than welcome to
> receive them.

Hear that folks!  I for one will give it a shot on a few classes and see
what happens.

> I'm  pretty sure we would never have got off the ground if this were the
case.
> Would *you* have paid $1000 for Dolphin Pro?

Not likely.  I confess I did wait through all your developments for this
version which can produce an .exe or .dll before buying.  And I hope to use
it to produce my own language someday as well as some profitable Smalltalk
stuff.  So I would like to understand certain things much better.

Kirk Fraser

Andy,

> You may be right but there was a pattern section on the Wiki for some
time,
> with the idea that others could contribute to it but nothing ever
> materialized. The contributors to this newsgroup, however, do sterling
work
> keeping the ship afloat. Of course, if anyone wants to submit well written
> documentation sections or class comments then we'd be more than welcome to
> receive them.

Some of that might be because effort expended on the newsgroup gets
preserved (courtesy of Ian), where the Wiki has been known to lose things
(whose fault is irrelevant - it happens).  I'm hesitant to spend time
updating pages that aren't necessarily there when I go back to refer to
them, either myself or as pointers in answering questions here.


> Given my stance about method comments, I don't think anyone (including
> myself and possibly even Beck) would disagree that having full
help/printed
> documentation/class comments/method comment *would* be desirable if there
> was no associated cost.  However, the cost of this stuff is high; not just
> in the writing but in the maintenance of it. It's like static typing..
> sometimes it can be useful but the costs (in
> writing/maintenance/flexibility)are just too onerous.

And the cost of not doing it?  IMHO, the new code that I'm seeing is going
to put the cost on the back end.   And I'm not sure I'm comfortable with the
analogy to strong typing.  That's perhaps in part because I don't expect
comments to be error-free; sometimes it's helpful to know what the developer
thought at some point in time (for formulating theories about what might be
wrong) or something close but not quite right might make the updated code
easier to understand.


> For example, each time we produce a new release of Dolphin the screendump
> graphics in the online documentation need to be redone. Each time we do
this
> we vow to write a tool to automate the process (still more time expended).

Agreed.  To some extent, I'm not sure I'd bother with the screen shots.  I
liked the days of the separate HTML files that were (amazingly at times)
informative once one got past the (sometimes frighteningly for beginners)
terse format.  Things like D5's package browser will require some more
how-to documentation, but the rest should probably focus on the timeless
concepts and perhaps direct considerable prose toward describing how and why
the IDE is sufficiently clean that one does not need huge volumes of
description to learn how to use it.


> Things get worse as the documentation gets lower towards the class and
> method level. The Refactoring Browser knows nothing about the contents of
> comments. If one changes a method or class name with the browser the
> comments have to be searched out and edited manually (or using old
fashioned
> tools like grep). Maybe the RB should be enhanced to handle comments more
> effectively but, again, that is still more effort.

Largely tangential to your point (which focuses on the content of comments),
the RB needs help with comments in cascades; it positions them in very
misleading ways, and is probably the biggest reason I've had to keep the RB
at arm's length.  I doesn't help to tweak the formatting of something that
is associated with the wrong node.

Have a good one,

Bill

--
Wilhelm K. Schwab, Ph.D.
[hidden email]

"Kirk W. Fraser" <[hidden email]> wrote in message news:<gPKA9.26860$A%[hidden email]>...
1) Nobody in XPLand ever said don't write comments. I say don't write
comments that are completely redundant, and work hard to make all
comments completely redundant, and repeatedly if folks try this they
end up with very few comments. The first job of every programmer is
communication-- with users, with managers, and with fellow
programmers. Use whatever tools are necessary to communicate.

2) Tests make wonderful documentation. I assume the code you refer to
was published (and perhaps written) without unit tests.

3) The wider and less personal the audience, the more written material
you will need aside from code and tests. That's why JUnit comes with
(some) printable documentation.

Kent

Kent Beck wrote:

> 1) Nobody in XPLand ever said don't write comments. I say don't write
> comments that are completely redundant, and work hard to make all
> comments completely redundant, and repeatedly if folks try this they
> end up with very few comments. The first job of every programmer is
> communication-- with users, with managers, and with fellow
> programmers. Use whatever tools are necessary to communicate.

But you are begging the question of how redundancy affects communication!

I claim (see elsewhere in this group recently) that redundancy is necessary
(or, at minimum, highly desirable) for effective communication.

    -- chris

"Chris Uppal" <[hidden email]> wrote in message news:<3ddaa28d$0$120$[hidden email]>...
x
  "Return the value of the instance variable x"
  ^x

Kent

Kent Beck wrote:

> x
>   "Return the value of the instance variable x"
>   ^x

Bit of a straw man, don't you think ?

What's wrong with the example (which I agree is ridiculous) is not that it is
redundant, but that it is useless -- in fact most likely wrong.

If the *meaning* (as opposed to the implementation) of the method is to give
read access to the 'x' variable, then the method's comment is accurate (and
highly unexpected, and -- as such -- not improper from any POV).  If so, and
it's going to exist without a comment (or even if it is) then a name like
#instavarNamedX, would be a far better choice.  (And anyway #instvarNamed:
would be a more generally "useful" method, in which case #instvarNamedX would
be an optimised version of #instvarNamed: specialised for retrieving that
particular instvar -- in which case the comment should give an indication of
*why* the optimisation was necessary).

But that's fantasy.  I can't imagine why anyone would want to have a method
with such a meaning.  In which case the comment is plain misleading.

If the method is actually part of (some flavour of) Point, then I'd accept that
'x' is the best choice for both the instvar name, and (almost coincidentally)
the method name.  Otherwise I strongly suspect that one or both is named less
informatively than it should be.  Whether, once it was properly renamed, a
method comment would be (more than redundant) *pointless* we can only guess.
My experience suggests that it would not be.

BTW, please remember that we are not talking about a context of co-located
developers with a tightly-coupled, shared understanding of a shared code-base.

(And yes, I do realise that XP calls for writing the *correct* amount of
commentary, given an intelligent and reflective understanding of what the
comments will be used for.  But -- oddly -- I've never heard of anyone saying
"Ah but XP teaches us that we should write more comments"...)

    -- chris

Kent, Chris,

> > x
> >   "Return the value of the instance variable x"
> >   ^x
>
> Bit of a straw man, don't you think ?

Or something written by a machine.  FWIW, I agree with the RB's "decision"
to not write such useless comments in accessors.  However, I will often add
one that tells what the variable is and/or why one should (or shoudn't!!<g>)
mess with it.

[SNIP]

> BTW, please remember that we are not talking about a context of co-located
> developers with a tightly-coupled, shared understanding of a shared
code-base.
>
> (And yes, I do realise that XP calls for writing the *correct* amount of
> commentary, given an intelligent and reflective understanding of what the
> comments will be used for.  But -- oddly -- I've never heard of anyone
saying
> "Ah but XP teaches us that we should write more comments"...)

Well said.  Despite intentions otherwise, the XP message has become:

(1) don't waste time writing comments or documentation
(2) tests catch everything, so just hack away
(3) BTW, you are going to hire my pair-programming parter too, right???

Try that at a job interview some time.  These are all things that have
gotten managers fired in the past, so they are quite reluctant to hop on
board.  Sorry, just the way I see it.

Have a good one,

Bill

--
Wilhelm K. Schwab, Ph.D.
[hidden email]

Bill,

>  Sorry, just the way I see it.

Good on yer for bucking the trend.

I find XP very interesting, and I have no difficulty believing that it works
(or can work if the conditions are more-or-less right).  I don't think it'd fit
too well with the way I work (maybe I should put that the other way around),
but just knowing it exists and works has helped me cure (or at least treat the
symptoms of) an ingrained tendency to over-engineer everything.

OTOH, I'm finding myself increasingly irritated by the apparent common
presumptions that Smalltalk implies XP or that XP is the *only* approach that
works.

    -- chris