--- Begin Message ---
Hi
I concur on the documentation problem.
I concur that there is plenty of documentation, but finding it is a chore.
I have two side projects I have started.
Doc at http://www.squeaksource.com/@FICALqrUmxQTIHgr/ul4_-exCAnd SeasideDoc
(which I started before Doc)
http://www.squeaksource.com/@FICALqrUmxQTIHgr/zwF3AJHc
I expect that I will develop Doc completely before refactoring SeasideDoc to
sit on top of it.
The core ideas are:
1. That documentation should be available in-image in familiar terms--by
sending messages to "stuff"
2. The documentation should be VERY EASY to add to (unlike the HelpBrowser,
which ,imho, is coding, not documenting).
3. StackExchange style commenting with upvotes, priority.
4. Doc saves to a normal repository squeaksource or however pharo does its
stuff, and hence, evolves with the image.
5. ?? this one is a stickler. should documentation be tightly bound with the
Objects per Class comment style? or should it exist symbiotically? I think the
latter. If so, what is the best design pattern(s) to facilitate that.
Regarding 1. ......by sending messages to "stuff"
stuff is..
classes: Dictionary doc
packages: PG3 doc
frameworks: Seaside doc
XTreams doc
Design Patterns: Singleton doc
Facade doc
BigBallOfMud doc (j.k.)
I think typical Gnu-Linux style "man" , "help" , "info" or "verbose" would be
an incredibly useful tool in bridging the "how do I do foo" gap that Squeak
certaintly has and I suspect Pharo does too.
I am very busy with a PEG grammar development project, so this is back burner
stuff for me.
I post this in the hope that some guru will take over the project and make
Pharo/Squeak/ (and other) Smalltalks the BEST documented systems on the
internet.
Cheers.
tty
---- On Mon, 29 Jun 2020 10:08:29 -0400 Tomaž Turk
<mailto:tomaz.t...@ef.uni-lj.si> wrote ----
Dear all,
This thread is a bit old, but anyways: here are my two cents on the question
'What are reasons not to use Smalltalk'. Thanks, Horrido, to constantly promote
these kind of discussions.
I think that your polls are mixing very different reasons - for instance, we
choose development tools in different settings: as a group, as a firm, as an
individual -- and for different purposes - for one of the projects, for some
projects, as a general orientation of a firm, a specific team, or an
individual. So I don't respond to these polls since it would be hard to answer
properly, and "all of the above" is probably useless to you.
What struck me about Pharo is the beauty and simplicity of the language and
environment - and its great community, of course! Despite the fact that I have
to use other tools because of my habits, environment, colleagues, students, and
customers, I keep running Pharo almost every day, testing the ideas - it became
a habit. I think that the consortium is well aware of the important things to
make Pharo a feasible toolset for serious development, like stability, the
proper GUI support, and books.
In my own experience, Pharo as a language is pretty mature. In every-day
situation with Pharo I deal with small challenges like remembering how to
change all spaces with hyphens in a String - as I do in other languages when I
try to remember all the methods that are already made for me in a certain
language/libraries. This is not a problem.
The real challenge is somewhere else: it's the comprehension of all the
packages that are needed for a full-size project, from persistence to GUI. When
documentation is scarce you have to go more or less deep into the code which I
often find quite challenging. Besides commentaries, it helps tremendously if
developers would always use typed variables to indicate API, like
properties: aDictionary
or
presentWith: aWAPresenter
instead of
properties: someProperties
and
presentWith: anObject
It's true that Pharo is not among "strongly typed" languages, however we
sometimes forget that typing is not just a technical thing to avoid run-time
errors, but it also gives information to other developers what's going on in
the code and who should be the receiver.
In some packages I also miss the use of superclasses - you can see that a bunch
of classes directly inherits from Object or some other general class, however
they could be organized in a better inheritance hierarchies, thus additionaly
explaining their common and individual behaviour.
Both and many other concepts are nicely described in books Learning OOP and
Pharo with Style. I know that we are always eager to develop the package and
satisfied when it works - and then it's hard to find the time to tie up these
little pieces. I hope I don't sound too patronizing - I'm the same myself.
Years ago Borland made a breakthrough with Turbo Pascal and Turbo C. For both
tools they prepared two sets of books: user manual and reference manual. Books
about Pharo are very nice and helpful, they are user manuals. If all the
crucial packages would respect typed variables and class hierarchies, we won't
need reference manuals at all :-)
So, yeah, I think that the tipping point for Pharo is the question of how much
time a developer should use to rediscover the behaviour which is already there.
Best wishes
Tomaz
--- End Message ---
