[Pharo-users] The cool implication of gtDocumentor gluing examples and how we might augment source naviagation

Tim Mackinnon tim at testit.works
Tue Jun 26 08:57:26 EDT 2018


Hi Doru - I’ll comment inline below:

> On 26 Jun 2018, at 13:05, Tudor Girba <tudor at tudorgirba.com> wrote:
> 
> Hi,
> 
>> On Jun 26, 2018, at 1:16 PM, Tim Mackinnon <tim at testit.works> wrote:
>> 
>> Hi guys - not sure how many people noticed this, but at the end of the tutorial for gtDocumentor, there is a section on Examples as Documentation.
> 
> Thanks for going through the tutorial. Quick questions:
> - how did it feel to go through it?
> - did applying changes work fine for you?
> - was there any confusion about what happened and where you were in the tutorial?
> - anything missing that might have helped?

Going through the tutorial felt reasonably intuitive (I have sort of seen people use Jupyter from afar, so I guess I had an idea of what it was trying to do)

I did notice that when I click on the Apply buttons, the change to “Applied” was a bit subtle - particular if you scroll back to see if you missed a step. So not sure if colouring the applied buttons or having some kind of Tick might make it a bit more obvious (but it wasn’t that bad)

Applying the changes seemed to work fine - sometimes examples took a bit of time, (but there is the progress indicator top left - although I was looking at the button that I clicked, so maybe some subtle feedback there might help as well)

I didn’t really get confused - however I will confess I only superficially followed along and didn’t question any of what it was telling me (e.g. what methods actually got created etc.). But conceptually it felt compelling and I believed it. 

I did find it a little bit sluggish to scroll (on a MacBook Pro 13” 2015 16gb ram) - so sometimes I over scrolled  - I also kind of missed having a proper scrollbar in the window to help me understand how far down I was. I already mentioned the diff pane scrolling issue. Also, only being able to resize output boxes down was sometimes a bit frustrating (but workable)

I wasn’t clear on whether I was supposed to be able to edit the markup myself while reading - e.g. putting * around some text didn’t make it bold (I kind of thought it might - but maybe that’s not supported?)

When I click on the + or - magnifying glasses, I also can’t scroll anymore (so its not like a zoom level - but again maybe this is just how its supposed to work? - clicking circle/square icon put it back to 100% and it worked fine).

Before I loaded the full gToolkit, I did get some messages about things being undefined - but the example still worked and I understood I needed to load something else (and hence asked you here).

Something that did cross my mind (and this was something I questioned about Jupyter) - if you want to reuse intermediate results - as in assign a script result to a variable and then reference later down in your text (like when doing a math’s problem) - it wasn’t clear if that is possible and obvious. Something like 

X := ${example:GtExamplesTutorial>>#createFileInMemory}$

And then you talk about X and then demonstrate something like (making use of X):

${example:GtExamplesTutorial>>#selectUppcaseLinesFrom: X}$

I’m guessing you can hide it all in the image with global variables - but I was thinking about how we auto define variables in the playground, and then incorporating those in the narrative.

Anyway I was very impressed (as was the group at UK Smalltalk) - there is lots of legs in this.

Tim

P.s. It was cool that the inspectors work and jump into the gtInspector stuff. I wasn’t clear on what all the different tabs are - maybe of which are similar (_Pillar vs _GT) - but I assume this is just the WIP nature of it. I did also get a few talkbacks clicking on items in the inspector -but again WIP or just missing dependencies?


> 
>> What is neat (and easily missed) is how when an example references another - there is a little triangle you can toggle to expose that example inline. (See photo).
>> 
>> This isn’t a completely new ideas (didn’t Newspeak hopscotch do this?) but its very well done in gtDocumentor and this implication could be that if our code editors had this too - then its very handy to unfold code to understand it in one place without having to open new windows. (I still think there are times when you may want to do that - particularly for long chains of methods?) but its certainly an idea that I would be very receptive to having in our code browsers (heck - give me all of gtDocumentor in our source editors).
> 
> This actually a new take on the nature of an editor. Hopscotch did not allow expanding things inside the text editor. The editor was always a leaf, and it is so in all editors I have seen so far. In our case, the triangle is added live by the syntax highlighter. Right now, we only use it for navigating examples both because we needed to explore how we can make deeply nested examples simple to reason about, and because we wanted to validate the Bloc architecture.
> 
> Of course, this ability is usable in many different ways. For example, the embedding in Pillar of various artifacts is done using the same mechanisms. And I think you will start seeing all sorts of applications in the UI area that you will simply not see in other places.
> 
> 
>> I’m wondering what others thing of this? Perhpas not for Pharo 7 - but Pharo 8 (pretty please?)
>> 
>> Tim
>> 
>> p.s. Note to @feenk, as its the last example its incredibly tricky to expand it to actually see it well as you can’t scroll further down to then drag the window bigger. I had to add a lot of Cr’s to make some space to do this.
> 
> Thanks. Indeed, the resizer solution you see now is just a first attempt without much polishing.
> 
> 
> Cheers,
> Doru
> 
> 
>> <PastedGraphic-1.png>
>> 
>> 
>> 
> 
> --
> www.tudorgirba.com
> www.feenk.com
> 
> "Problem solving efficiency grows with the abstractness level of problem understanding."
> 
> 
> 
> 
> 




More information about the Pharo-users mailing list