Thanks for your comments and questions. We will try to address them in a second version of the documentation, together with the other questions and answers that have appeared on the mailing list in the mean time.
So, if anybody else has more comments and questions, do ask. They will be integrated in a second iteration of the documentation! On Feb 16, 2014, at 9:34 AM, 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. > > ---> Save our in-boxes! http://emailcharter.org <--- Johan Fabry - http://pleiad.cl/~jfabry PLEIAD lab - Computer Science Department (DCC) - University of Chile
