[ANN] Spec documentation in PFTE book finished
Locked
 
|
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 |
Re: [Pharo-dev] [ANN] Spec documentation in PFTE book finished
|
|
Thanks a lot, Johan & Ben, this is great work !
On 12 Feb 2014, at 16:08, Johan Fabry <[hidden email]> 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 > > |
Re: [ANN] Spec documentation in PFTE book finished
|
|
In reply to this post by jfabry
" Creating a specific UI always starts with the subclassing of ""ComposableModel"". The above is passive with 2 gerunds. especially if the reader may be using English as a second language or merely know English as a technical language.
"To specify a UI, you must first declare a subclass of ComposableModel." But Smalltalkers use "subclass" as a verb, so we get 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 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 <[hidden email]> wrote: Hi all, |
Re: [ANN] Spec documentation in PFTE book finished
|
|
In reply to this post by jfabry
humour: license to practice English humor note; 'subclass' may be a verb at wiktionary.org but not in current standard English (e.g. m-w.org or 2002 10th Ed, hardcover Merriam-Webster) ... so word is being used as a technical term in 2014 ... life was easier when a verb had one spelling and a noun another ... but 200+ yrs ago that divide was replaced by the Atlantic Ocean ... never-to-be :
On 12 February 2014 11:08, Johan Fabry <[hidden email]> wrote: Hi all, |
Re: [ANN] Spec documentation in PFTE book finished
|
|
In reply to this post by LogiqueWerks
On Thu, 13 Feb 2014 12:42:59 -0000, Robert Shiplett <[hidden email]> wrote:
But is perfectly good and clear English nonetheless.
|
|
|
In reply to this post by LogiqueWerks
Ben and I focused on getting a readable text out there that is useful for people wanting to use Spec. Personally, having experience with writing lots of English, I'm actually quite happy with how it turned out and I think the text is quite readable. This being said, we are nonnative English speakers (and writers) and I am sure that there are worse sentences than this one in the text. I don't think this one is bad at all, actually. If a decision is made by the people coordinating the PFTE book to appoint an editor, I'm sure Ben and I will be happy to cooperate. On Feb 13, 2014, at 9:42 AM, Robert Shiplett <[hidden email]> wrote: > " > 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 - ---> Save our in-boxes! http://emailcharter.org <--- Johan Fabry - http://pleiad.cl/~jfabry PLEIAD lab - Computer Science Department (DCC) - University of Chile |
Re: [ANN] Spec documentation in PFTE book finished
|
I think its great that Spec has finally documentation, it makes it far easier for me to use Spec and evaluate its usefulness. Thank you for your effort.
On Thu, Feb 13, 2014 at 4:57 PM, Johan Fabry <[hidden email]> wrote:
|
Re: [ANN] Spec documentation in PFTE book finished
|
|
On Thu, 13 Feb 2014 15:08:32 -0000, kilon alios <[hidden email]> wrote:
Seconded. If the English is at this level all the way through I, as a native English speaker, won't have any complaints. It's great to have some documentation done and it's much appreciated. TW
|
|
|
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. |
Re: [ANN] Spec documentation in PFTE book finished
|
|
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 <[hidden email]> wrote: The Spec documentation is very good /as far as it goes/. As a native speaker, |
|
|
I would be happy to write some Spec documentation - when I start to understand it better. I've gained some idea of how the TreeModel works so perhaps i could do something on that and you could roll it into the Spec documentation somewhere. Just a suggestion.
Meanwhile expect a barrage of questions about Spec on this mailing list as I start to look at Spec more closely. |
Re: [ANN] Spec documentation in PFTE book finished
|
|
Any questions are welcome :)
Ben On 16 Feb 2014, at 14:19, kmo <[hidden email]> wrote: I would be happy to write some Spec documentation - when I start to |
|
|
In reply to this post by kmo
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 <[hidden email]> 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 |
|
|
In reply to this post by kmo
Hi,
Just reviewing the old message I found this: [...] > > 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./ I mean to be constructive, some please be patient if I can't express myself properly, but I have this impression of being "self-absorbed" on the documentation of Agile Visualization. As I have said my workshops with people here are something like: 1. Wow! Pharo is so easy to install and to get beautiful visualizations. 2. Where the data comes from? Ohh is mostly about the data that Pharo contains about itself. How can I add new data? I think that we need a way to show that new data can be added easily. For example would be nice to have a visualization about what happens on social networks like twitter with a graph. and having ways to show data as tables that can be editable more directly (like a spread sheet) instead of the indirect manipulation of "static" data like the ones in earthquakes examples. I will try to help implementing my suggestions but maybe people working on documentation could think about how to make it less self-absorbed with Pharo itself and more around data from the external world. Cheers, Offray |
Re: [ANN] Spec documentation in PFTE book finished
|
|
> On 28 Dec 2014, at 19:05, Offray Vladimir Luna Cárdenas <[hidden email]> wrote: > > Hi, > > Just reviewing the old message I found this: > > [...] > > >> 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./ > > I mean to be constructive, some please be patient if I can't express myself properly, but I have this impression of being "self-absorbed" on the documentation of Agile Visualization. > > As I have said my workshops with people here are something like: > > 1. Wow! Pharo is so easy to install and to get beautiful visualizations. > 2. Where the data comes from? Ohh is mostly about the data that Pharo contains about itself. How can I add new data? > > I think that we need a way to show that new data can be added easily. For example would be nice to have a visualization about what happens on social networks like twitter with a graph. and having ways to show data as tables that can be editable more directly (like a spread sheet) instead of the indirect manipulation of "static" data like the ones in earthquakes examples. > > I will try to help implementing my suggestions but maybe people working on documentation could think about how to make it less self-absorbed with Pharo itself and more around data from the external world. I agree, there should be more examples about real-world stuff as opposed to meta information about programming. Of course, that *is* Moose's origin. Now, I have seen various examples with maps ... It should also be quite easy to load any public data in Pharo. We got HTTP(S) functionality, can open/read any file, parse CSV, JSON, XML and so on straight into objects. I am always willing to help if anyone struggles with any of my frameworks. > Cheers, > > Offray > |
|
|
I would be interested by having an example that I could use to rewrite
the spec documentation: - would be good to have a kind of container relationships to be able to display multiple list - the model should not be too complex to explain. So if you have data and idea I'm all ears. Stef Le 28/12/14 19:16, Sven Van Caekenberghe a écrit : >> On 28 Dec 2014, at 19:05, Offray Vladimir Luna Cárdenas <[hidden email]> wrote: >> >> Hi, >> >> Just reviewing the old message I found this: >> >> [...] >>> 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./ >> I mean to be constructive, some please be patient if I can't express myself properly, but I have this impression of being "self-absorbed" on the documentation of Agile Visualization. >> >> As I have said my workshops with people here are something like: >> >> 1. Wow! Pharo is so easy to install and to get beautiful visualizations. >> 2. Where the data comes from? Ohh is mostly about the data that Pharo contains about itself. How can I add new data? >> >> I think that we need a way to show that new data can be added easily. For example would be nice to have a visualization about what happens on social networks like twitter with a graph. and having ways to show data as tables that can be editable more directly (like a spread sheet) instead of the indirect manipulation of "static" data like the ones in earthquakes examples. >> >> I will try to help implementing my suggestions but maybe people working on documentation could think about how to make it less self-absorbed with Pharo itself and more around data from the external world. > I agree, there should be more examples about real-world stuff as opposed to meta information about programming. Of course, that *is* Moose's origin. > > Now, I have seen various examples with maps ... > > It should also be quite easy to load any public data in Pharo. We got HTTP(S) functionality, can open/read any file, parse CSV, JSON, XML and so on straight into objects. I am always willing to help if anyone struggles with any of my frameworks. > >> Cheers, >> >> Offray >> > > |
Re: [ANN] Spec documentation in PFTE book finished
|
|
I have about 1/2 of an application written to implement PERT, which is something management types study for doing project cost estimation, but usually don't use in reality. It has a nice container hierarchy (Project > Phase > Task > Task > ... > Task). I have part of the UI written in Glamour and part in Spec, but it isn't finished. I'm using this as a tutorial to teach my wife Pharo—although I'm probably not so great at it that I should be teaching anybody. :) The tutorial isn't as far along as the application and is probably wrongly titled at this point. I'm happy to give away the code and the tutorial but I'm a little stuck now since we have just had a baby and are now preparing to move in three weeks. So I apologize for the rough state of affairs, but since you asked I only hope it may be better than nothing. The tutorial can be read here: http://st.7gf.org/PERT/ Markdown source: http://st.7gf.org/PERT/PERT.md Additionally I have a whiteboard capture of the interface I envision with Glamour (which may or may not be appropriate). The size is quite large despite the low quality, my apologies: It would be hard to come up with a more "boring" and "business" application domain than this… but for management people the problem is pretty well-known and for my wife, her only prior programming experience (not counting Excel) is C and the experience has been positive for her so far. She's also greatly enjoying going through my paper copy of Pharo by Example and the built-in tutorial. The basic concept, in case anyone is interested, is that you can form a directed acyclic graph between subtasks and then using min/max cost estimates, determine which tasks are "critical" and which tasks can be late without affecting the deadline or budget. The "project window" above uses a GLFinder-like approach to allow drilling down into subtasks from projects and phases. This means you're stuck with a tree instead of a DAG. The target level of sophistication for the final application is one that can use expected costs and a beta distribution to simulate thousands of different possible outcomes and then aggregate from there to see which tasks are likely to be troublesome or have bad estimates. This is what is pictured in the simulation-window mockup. The project graph diagram is just a sketch of something that would be trivial to do with Roassal. The project and task/activity objects should be fairly obvious. Phase is just recognition of the idea that projects are usually implemented in phases, and you usually have to complete one phase before starting the next: e.g., you must have made the prototype before you can put it into production. This layer is unnecessary from a computational point of view (there's nothing like it in the wiki page for PERT either) but it's a helpful organizational tool, plus it lets you create a nice boundary to get back some of the nice things about having a DAG that you lose with a tree representation. I don't know if this is what you're looking for or not but here it is. All the best,
—
Daniel Lyons |
Re: [ANN] Spec documentation in PFTE book finished
|
|
All that and I forgot to include the link to the code.
—
Daniel Lyons |
|
|
In reply to this post by Daniel Lyons
thanks I will have a look.
Now busy building furnitures :) Le 2/1/15 08:36, Daniel Lyons a écrit :
|
«
Return to Pharo Smalltalk Users
|
1 view|%1 views
| Free forum by Nabble | Edit this page |