The cool implication of gtDocumentor gluing examples and how we might augment source naviagation

> On 26 Jun 2018, at 13:05, Tudor Girba <[hidden email]> wrote:
>
> Hi,
>
>> On Jun 26, 2018, at 1:16 PM, Tim Mackinnon <[hidden email]> 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?

>
>> 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."
>
>
>
>
>

> On Jun 26, 2018, at 2:57 PM, Tim Mackinnon <[hidden email]> wrote:
>
> Hi Doru - I’ll comment inline below:
>
>> On 26 Jun 2018, at 13:05, Tudor Girba <[hidden email]> wrote:
>>
>> Hi,
>>
>>> On Jun 26, 2018, at 1:16 PM, Tim Mackinnon <[hidden email]> 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)

>
>>
>>> 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."

> On 26 Jun 2018, at 18:14, Tudor Girba <[hidden email]> wrote:
>
> Hi Tim,
>
> Thanks a lot for the detailed comments! More inline.
>
>
>> On Jun 26, 2018, at 2:57 PM, Tim Mackinnon <[hidden email]> wrote:
>>
>> Hi Doru - I’ll comment inline below:
>>
>>> On 26 Jun 2018, at 13:05, Tudor Girba <[hidden email]> wrote:
>>>
>>> Hi,
>>>
>>>> On Jun 26, 2018, at 1:16 PM, Tim Mackinnon <[hidden email]> 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)
>
> Ok.
>
>> 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)
>
> Ok.
>
>> 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.
>
> This is great!
>
>> 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)
>
> What do you mean by only being able to resize down? You should be able to resize them up as well. Or did I misunderstand?
>
>> 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?)
>
> Bold is not added in the highlighter. Indeed, what you see is a live editor so editing is intended. However, we still have a few issues with it. While they are small, the experience can appear brittle at the moment.
>
>> 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).
>
> Thanks. We have to update those.
>
>> 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).
>
> Ok.
>
>> 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.
>
> The document already provides an out variable with the output of the previous snippet, and and outs variable with all results. However, we do want to extend this a bit more. For example, if you define a variable in a script, that variable will be usable in other snippets throughout the document.
>
> Indeed, we can bring the narrative significantly further than it is now.
>
>> Anyway I was very impressed (as was the group at UK Smalltalk) - there is lots of legs in this.
>
> Thanks!
>
>> 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?
>
> We are now in a transition period: because we do not have windows and enough widgets in Bloc, we are reusing the existing Morphic-based infrastructure. All presentations that start with _ are rendered in Bloc. _GT is the new bloc-based inspector that has its own extension mechanism. This is what you see when you execute a snippet in Documenter. So, when in the Bloc world, you will only see Bloc based renderings. So, in the near future we will start to get more duplicated renderings(one in Bloc one in Morphin) for various objects.
>
> Cheers,
> Doru
>
>>
>>>
>>>> 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."
>
> --
> www.tudorgirba.com
> www.feenk.com
>
> "We can create beautiful models in a vacuum.
> But, to get them effective we have to deal with the inconvenience of reality."
>
>