" Creating a specific UI always starts with the subclassing of ""ComposableModel"". "
The above is passive with 2 gerunds. No experienced tech editor should let that pass as an English instruction for an action or task to be performed by a reader - especially if the reader may be using English as a second language or merely know English as a technical language. ALT non-passive sentence "To specify a UI, you must first declare a subclass of ComposableModel." But Smalltalkers use "subclass" as a verb, so we get "To specify a UI, you must subclass ComposableModel first." ALT How to specify a UI : First step : subclass ComposableModel ( we will declare ModelList in this class browser UI example.) Some of the Wiley "For Dummies" books offer good examples, as do some of the "Idiot's Guide" books. Some books in German offer examples only rivalled by books in Japanese. Sadly, English invites abstract constructions using Latin roots instead of simple Anglo-Saxon verbs. Japanese at least places a verb at the end of the sentence and has "ga" to distinguish true subjects from mere topics indicated by 'wa". German has the frightful practice of ending sentences with prepositions. Relatively more synthetic or analytic languages pose different challenges for technical clarity in explaining practical tasks such that an example can serve as an exemplary instance for future reference to refresh recall and to facilitate recognition. Boeing and NASA have some experience here : Apollo 13 has a reminder of the challenge of impedance mis-match and "round" meets "square"component. Note: the practical "principles" for landing light planes with power are not those for landing heavy jets with power, partly because piston engines do not "spool up" ; runway "flare" is not achieved by "Looking at how close you are to the runway" but must be learned - partly on the ambient flow of a visual gradient ... except in marginal visibility or over water or over waving tall grass ... Clear technical English is a challenge : it is not met by "knowing English" anymore than landing an airplane is achieved by knowing the names of the yoke and rudder ( and beware of rudder-less aircraft ! ) Can someone other than me volunteer as a technical editor ? It is not a matter of having the facts right or mentioning the "Gotcha's". For an MVP example, I would suggest giving the use of colour some serious thought : experiment with it. It is now used in some new bilingual dictionaries to very good effect. If you have never looked at a surgical manual for a new procedure, I would suggest doing so. Ask a spouse about the most useless instruction manual for the DIY project that refused to assemble. The writer of the latter also "knew" enough English to write the instructions. No offense intended WHATSOEVER and I hope none taken by anyone. As Marcus may recall, I now have more difficulties typing at a keyboard and even in the short term I may become less helpful and less useful. Perhaps there is a tool for blue-pen and red-pen : PDF annotations ? There should be a Smalltalk UI for editing text in tX ... ;-) R Canada PS For some readers, MVP can be no more obvious than MVC ; believing in MVP as being more obvious could impede presentation. MVC was a stumbling block for many learning to build UI's in various Smalltalk dialects in the past. Do you recall handing off a Smalltalk project for maintenance to someone who believed in C++ but was moved to your ST group or team ? I remember this very clearly. You can learn a lot from a dummy. I learned a bit from having taught English as a second-language to Vietnamese and to Poles that I did not learn teaching French students. A book for the "Enterprise" is surely not aimed chiefly at those of us who have enjoyed drinking the Kool-Aid ;-) On 12 February 2014 11:08, Johan Fabry <jfa...@dcc.uchile.cl> wrote: > Hi all, > > I am happy to announce that Ben and I finished the documentation of Spec > for the Pharo For The Enterprise book. This documentation is up-to-date > with the latest version of Spec, and is focused towards people wanting to > use it and even extend it (in contrast to the academic papers which are … > academic ;-) ). I hope that this text will help all the people that are > building UIs in Pharo, and it will clear up any doubts that they may have. > > The chapter is available in source form from the GitHub project of the > PFTE book: > https://github.com/SquareBracketAssociates/PharoForTheEnterprise-english > > The easiest way to read the chapter is from the continuous integration > server, which produces a html file of the chapter here: > > https://ci.inria.fr/pharo-contribution/job/PharoForTheEnterprise/lastSuccessfulBuild/artifact/Spec/Spec.pier.html > (The same server also produces pdf and markdown files, but there are some > strange artifacts there, currently. I guess this will be cleared up in the > future) > > We tried our best to make it understandable and complete, but if you have > any doubts or comments please do not hesitate to let us know !! Ben prefers > Github apparently, but if you are oldskool like me you can also send a mail > (privately or to the mailing list). > > Now it's time to build some cool user interfaces! :-) > > ---> Save our in-boxes! http://emailcharter.org <--- > > Johan Fabry - http://pleiad.cl/~jfabry > PLEIAD lab - Computer Science Department (DCC) - University of Chile > > >
