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.
