Thank you for your review :)
I have to agree with you and to answer briefly,
the main problems with documentation is:
- it takes time (*a lot* to me since I am more a code than a writer :P)
- things evolve (that can be managed though)
I will be super happy to have a more complete documentation
I spend(t) time on it (and Johan too, thank you very much again :) ).
Now I will be even happier to review any pull request ;)
Ben
On 16 Feb 2014, at 13:34, kmo <vox...@gmail.com> wrote:
> The Spec documentation is very good /as far as it goes/. As a native speaker,
> I would say the English is excellent, though the tone is rather dry and
> technical. Generally, I think it is well written and very helpful. That's
> not the issue.
>
> The real problem is that this documentation is no more than an overview. It
> is not written from a /How To/ perspective. The result is that it offers
> little help to anyone who wants to actually create a user interface with
> Spec.
>
> Here are some obvious questions that might occur to anyone starting to use
> Spec. None of them are answered in the current documentation.
>
> How do use Spec to write an application that fills the pharo window? (There
> is no mention of openWorldWithSpec in the document).
>
> How do I write an application with a main menu at the top, a toolbar under
> it, and a status bar at the bottom?
>
> How to I create, use and close, non-modal windows in my application?
>
> How do I write a modal dialog, ask for complex information, and get it back?
> (There is a modal dialog example in the document under Prototyping a UI but
> nothing explicit).
>
> How do I use a SliderModel, RadioButtonModel etcetera?
>
> How do I use all those cool Morphs I've found - PianoKeyboardMorph, LEDMorph
> etcetera - with Spec? Surely I don't have to write my own Morphic Adapter
> for each one?
>
> How do I migrate my Morphic application to Spec?
>
> To my mind, this document is only the beginning. It doesn't even have a list
> of the available Spec models and their APIs - even the original Spec Report
> had a table of these. The approach seems to be - here's a general idea of
> how it works - read the source if you actually want to do anything. Well,
> even an idiot like me can perhaps work out how to use a LabelModel, but
> TreeModel,say, with its TreeColumns and TreeNodes is not so obvious and it
> needs trial and error to find out how it all fits together (not helped by
> the complete abscebnce of helpful class comments). We don't need tail and
> error. We need documentation.
>
> Finally, can we please stop using class browsers as examples? I know that it
> is easy (and cool) to use reflection to get lists of classes, protocols and
> methods but this only adds to the impression that the smalltalk community is
> self-absorbed and narcissistic. If you want to attract business developers
> then use examples that relate to the real world, not to the pharo
> environment itself. Why not a database example or a paint application
> example? No one wants to write a class browser - that's already available!
>
> Perhaps I should stop before this becomes filed under /Why is
> smalltalk/pharo so unpopular./
>
> To sum up, this documentation is a good start - but that's all it is.
>
>
>
>
>
>
>
>
>
> --
> View this message in context:
> http://forum.world.st/ANN-Spec-documentation-in-PFTE-book-finished-tp4743035p4744054.html
> Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.
>
