On Thu, 13 Feb 2014 12:42:59 -0000, Robert Shiplett <grshiplett@gmail.com> wrote:

" Creating a specific UI always starts with the subclassing of ""ComposableModel"". "

The above is passive with 2 gerunds.

But is perfectly good and clear English nonetheless.

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 <jfabry@dcc.uchile.cl> wrote:

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 <grshiplett@gmail.com> 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

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-tp4743035... Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.

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. -- View this message in context: http://forum.world.st/ANN-Spec-documentation-in-PFTE-book-finished-tp4743035... Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.

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 <voxkmp@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-tp4743035... 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

On 28 Dec 2014, at 19:05, Offray Vladimir Luna Cárdenas <offray@riseup.net> 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

On Dec 28, 2014, at 3:17 PM, stepharo <stepharo@free.fr> wrote:

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.

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/ <http://st.7gf.org/PERT/> PDF: http://st.7gf.org/PERT/PERT.pdf <http://st.7gf.org/PERT/PERT.pdf> Markdown source: http://st.7gf.org/PERT/PERT.md <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: http://st.7gf.org/PERT/project-window <http://st.7gf.org/PERT/project-window>.jpg http://st.7gf.org/PERT/simulation-window.jpg <http://st.7gf.org/PERT/simulation-window.jpg> http://st.7gf.org/PERT/project-graph-diagram.jpg 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

thanks I will have a look. Now busy building furnitures :) Le 2/1/15 08:36, Daniel Lyons a écrit :

...

On Dec 28, 2014, at 3:17 PM, stepharo <stepharo@free.fr <mailto:stepharo@free.fr>> wrote:

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.

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/ PDF: http://st.7gf.org/PERT/PERT.pdf 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:

http://st.7gf.org/PERT/project-window.jpg http://st.7gf.org/PERT/simulation-window.jpg http://st.7gf.org/PERT/project-graph-diagram.jpg

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