Quick Start User Experience

I took the notes below while going through the chapter. In summary:
- maybe RTTabTable is mis-packaged?
- it's hard to keep written examples up-to-date with the code, especially when they are not automatically tested (of course in my dreams we only have active essays and never run into this problem, yet I digress...)
- Code comments are key for when users want to drop into the code quickly from an example in the documentation to adapt it to our own needs
- Nagging thought (not specific to the chapter): most of the Roassal examples I've seen illustrate procedural scripts. It might be nice to have more OOP examples, or if the point is to target non-programmers/Smalltalkers, at least a disclaimer saying that they're in script form for simplicity of copy/paste or whatever, but a real-world OOP example can be downloaded at...

Roassal Quick Start says to visualize CSV data starting with RTTabTable, but shows the table plotted on a map, which does not fit my use case. It seems like I should be able to use the table not-on-a-map, but I see that it’s in the Builder-Map package, so I’m not so sure. In the end, that works out okay because I see that it’s reused in the Timeline example.

Just as an experiment, I adapt the timeline example. Most of it is straightforward except the send of #normalizeSize:min:max:using: which was hardcoded and makes my data huge. I’d like to adjust it, but neither the method nor its class (RTMetricNormalizer) has a comment and I can’t figure it out from the example senders. Oh, well it was just an experiment…

Next up, the charting example. First hurdle: #axisXNoLabelledWithNumberOfTicks: does not seem to exist in the system (fresh download from the link at the start of the chapter). I shorten it to axisXWithNumberOfTicks:, which works but the resulting chart is overcrowded with X axis labels. The example now works, but it’s hard to figure out what’s going on to adapt it to my use. For example, allY: is not a meaningful name to me and there is no method comment.

HTH.

Tx this is a great feedback

On 20/8/14 14:37, Sean P. DeNigris wrote:
_______________________________________________
Moose-dev mailing list
[hidden email]
https://www.iam.unibe.ch/mailman/listinfo/moose-dev

Hi Sean,

Thanks for this wonderful feedback.

> - maybe RTTabTable is mis-packaged?

You’re very right. Classes related to TabTable are now in Roassal2-Utility

> - it's hard to keep written examples up-to-date with the code, especially
> when they are not automatically tested (of course in my dreams we only have
> active essays and never run into this problem, yet I digress…)

I agree. I am considering in moving to Pillar.

> - Code comments are key for when users want to drop into the code quickly
> from an example in the documentation to adapt it to our own needs

The Quick Start chapter tries to comment on each example. Which of the examples are not clear for you?

> - Nagging thought (not specific to the chapter): most of the Roassal
> examples I've seen illustrate procedural scripts. It might be nice to have
> more OOP examples, or if the point is to target
> non-programmers/Smalltalkers, at least a disclaimer saying that they're in
> script form for simplicity of copy/paste or whatever, but a real-world OOP
> example can be downloaded at…

Most of the provided scripts are rather short. I am convinced that non-programmers should be confortable at scripting, even long script. We should provide a nice infrastructure for this.

> Roassal Quick Start says to visualize CSV data starting with RTTabTable, but
> shows the table plotted on a map, which does not fit my use case. It seems
> like I should be able to use the table not-on-a-map, but I see that it’s in
> the Builder-Map package, so I’m not so sure. In the end, that works out okay
> because I see that it’s reused in the Timeline example.

That is fixed. I moved RTTabTable and its close friends to a distinct class category.

> Just as an experiment, I adapt the timeline example. Most of it is
> straightforward except the send of #normalizeSize:min:max:using: which was
> hardcoded and makes my data huge. I’d like to adjust it, but neither the
> method nor its class (RTMetricNormalizer) has a comment and I can’t figure
> it out from the example senders. Oh, well it was just an experiment…

I do not understand what you mean by “hardcoded”. You can use #normalizeSize:min:max:using: the way you wish. Which behavior to you want to have that #normalizeSize:min:max:using: does not address for now?

> Next up, the charting example. First hurdle:
> #axisXNoLabelledWithNumberOfTicks: does not seem to exist in the system
> (fresh download from the link at the start of the chapter). I shorten it to
> axisXWithNumberOfTicks:, which works but the resulting chart is overcrowded
> with X axis labels. The example now works, but it’s hard to figure out
> what’s going on to adapt it to my use. For example, allY: is not a
> meaningful name to me and there is no method comment.

Yes. This is a part of the API I am not too sure about. Probably I will remove x: and y: and rename allX: and allY: into x: and y:

Thanks for your comments. They are very valuable.
I owe you some beers at the next Esug.

In the meantime, I have updated the QuickStart and Charter chapters.

Please continue!
Alexandre


_______________________________________________
Moose-dev mailing list
[hidden email]
https://www.iam.unibe.ch/mailman/listinfo/moose-dev

Indeed!
_______________________________________________
Moose-dev mailing list
[hidden email]
https://www.iam.unibe.ch/mailman/listinfo/moose-dev