Hi Doru - I’ll comment inline below:
> On 26 Jun 2018, at 13:05, Tudor Girba <tu...@tudorgirba.com> wrote:
>
> Hi,
>
>> On Jun 26, 2018, at 1:16 PM, Tim Mackinnon <tim@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."
>
>
>
>
>
