Booklet suggestion

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

Booklet suggestion

Ben Coman
I've seen a few requests for short bits of code to use in playground for a demo presentation.  I wonder if it would be good to have a booklet to gather these - seeded with Sven's excellent article... 

It could include the recent meta-programming scripts like searching for all class instance variables starting with a capital letter.

The book might be named "Snippets", in a format presentable to laser print on-site - something physical for attendees to take away with them to quick demo to others back in their office.

I can take the lead in setting it up.  Anyone remember any relevant posts in our archives? 

cheers -ben
Reply | Threaded
Open this post in threaded view
|

Re: Booklet suggestion

K K Subbu
Ben,

I think there is a deeper need here. Writing good document is hard and
keeping it in sync with code is harder still.

A book/booklet separates content from the code and being frozen in time
faces obsolescence. I would prefer to see a guidebook framework in Pharo
that every package author can use to create a simple narrative on its
features. Package authors and consumers have an incentive to keep the
code and content in sync. If an Object is a recursion on the notion of a
computer, why not provide, say a Note, as a recursive simplification of
a book?

The framework could be on the lines of Plugins, Tests. E.g.

    Package-Core
    Package-Plugins
    Package-Tests
    *Package-Guide*

The guide framework should support active code (say to pop the source
code for a method), active links to guides on which this package
depends, automatic generation of table of contents, index of class
references. Most of features already exists in Pharo but spread all
over. They need a home.

A package could also extend this basic framework with features (e.g. PDF
package could export articles to PDF, Zinc could generate HTML).

Regards .. Subbu

On Thursday 25 May 2017 07:03 AM, Ben Coman wrote:

> I've seen a few requests for short bits of code to use in playground for
> a demo presentation.  I wonder if it would be good to have a booklet to
> gather these - seeded with Sven's excellent article...
> https://medium.com/concerning-pharo/elegant-pharo-code-bb590f0856d0
>
> It could include the recent meta-programming scripts like searching for
> all class instance variables starting with a capital letter.
>
> The book might be named "Snippets", in a format presentable to laser
> print on-site - something physical for attendees to take away with them
> to quick demo to others back in their office.
>
> I can take the lead in setting it up.  Anyone remember any relevant
> posts in our archives?
>
> cheers -ben


Reply | Threaded
Open this post in threaded view
|

Re: Booklet suggestion

Ben Coman
Nice idea.  I've seen vague discussion about getting Pillar into the
standard image for documentation.
Perhaps it should be raised for consideration for Pharo 7?

Actually you stimulate my thoughts that the Help file might be a
better place for such snippets,
so they are always with the image, and don't need to be retyped.  Any
objections?

cheers -ben

On Thu, May 25, 2017 at 4:00 PM, K K Subbu <[hidden email]> wrote:

> Ben,
>
> I think there is a deeper need here. Writing good document is hard and
> keeping it in sync with code is harder still.
>
> A book/booklet separates content from the code and being frozen in time
> faces obsolescence. I would prefer to see a guidebook framework in Pharo
> that every package author can use to create a simple narrative on its
> features. Package authors and consumers have an incentive to keep the code
> and content in sync. If an Object is a recursion on the notion of a
> computer, why not provide, say a Note, as a recursive simplification of a
> book?
>
> The framework could be on the lines of Plugins, Tests. E.g.
>
>    Package-Core
>    Package-Plugins
>    Package-Tests
>    *Package-Guide*
>
> The guide framework should support active code (say to pop the source code
> for a method), active links to guides on which this package depends,
> automatic generation of table of contents, index of class references. Most
> of features already exists in Pharo but spread all over. They need a home.
>
> A package could also extend this basic framework with features (e.g. PDF
> package could export articles to PDF, Zinc could generate HTML).
>
> Regards .. Subbu
>
>
> On Thursday 25 May 2017 07:03 AM, Ben Coman wrote:
>>
>> I've seen a few requests for short bits of code to use in playground for
>> a demo presentation.  I wonder if it would be good to have a booklet to
>> gather these - seeded with Sven's excellent article...
>> https://medium.com/concerning-pharo/elegant-pharo-code-bb590f0856d0
>>
>> It could include the recent meta-programming scripts like searching for
>> all class instance variables starting with a capital letter.
>>
>> The book might be named "Snippets", in a format presentable to laser
>> print on-site - something physical for attendees to take away with them
>> to quick demo to others back in their office.
>>
>> I can take the lead in setting it up.  Anyone remember any relevant
>> posts in our archives?
>>
>> cheers -ben
>
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Booklet suggestion

askoh
Administrator
In reply to this post by K K Subbu
You gave me an idea.

Since Test Driven Design insists all tests passes before release, we can piggy back on that by insisting Tutorials, Demos, Examples be tests that must pass before release. Can we design Tutorials, Demos, Examples like tests? I think so.

All the best,
Aik-Siong Koh
Reply | Threaded
Open this post in threaded view
|

Re: Booklet suggestion

Stephane Ducasse-3
In reply to this post by Ben Coman
What I'm doing is 
- extracting a subset of pillar
- doc + renderer  
- so that we can use it in the image. 
Now kasper did a first version (in the repository and if people want to have a look it will help)
- now I'm remaving the dependency on magritte.

Stef

On Thu, May 25, 2017 at 2:03 PM, Ben Coman <[hidden email]> wrote:
Nice idea.  I've seen vague discussion about getting Pillar into the
standard image for documentation.
Perhaps it should be raised for consideration for Pharo 7?

Actually you stimulate my thoughts that the Help file might be a
better place for such snippets,
so they are always with the image, and don't need to be retyped.  Any
objections?

cheers -ben

On Thu, May 25, 2017 at 4:00 PM, K K Subbu <[hidden email]> wrote:
> Ben,
>
> I think there is a deeper need here. Writing good document is hard and
> keeping it in sync with code is harder still.
>
> A book/booklet separates content from the code and being frozen in time
> faces obsolescence. I would prefer to see a guidebook framework in Pharo
> that every package author can use to create a simple narrative on its
> features. Package authors and consumers have an incentive to keep the code
> and content in sync. If an Object is a recursion on the notion of a
> computer, why not provide, say a Note, as a recursive simplification of a
> book?
>
> The framework could be on the lines of Plugins, Tests. E.g.
>
>    Package-Core
>    Package-Plugins
>    Package-Tests
>    *Package-Guide*
>
> The guide framework should support active code (say to pop the source code
> for a method), active links to guides on which this package depends,
> automatic generation of table of contents, index of class references. Most
> of features already exists in Pharo but spread all over. They need a home.
>
> A package could also extend this basic framework with features (e.g. PDF
> package could export articles to PDF, Zinc could generate HTML).
>
> Regards .. Subbu
>
>
> On Thursday 25 May 2017 07:03 AM, Ben Coman wrote:
>>
>> I've seen a few requests for short bits of code to use in playground for
>> a demo presentation.  I wonder if it would be good to have a booklet to
>> gather these - seeded with Sven's excellent article...
>> https://medium.com/concerning-pharo/elegant-pharo-code-bb590f0856d0
>>
>> It could include the recent meta-programming scripts like searching for
>> all class instance variables starting with a capital letter.
>>
>> The book might be named "Snippets", in a format presentable to laser
>> print on-site - something physical for attendees to take away with them
>> to quick demo to others back in their office.
>>
>> I can take the lead in setting it up.  Anyone remember any relevant
>> posts in our archives?
>>
>> cheers -ben
>
>
>


Reply | Threaded
Open this post in threaded view
|

Re: Booklet suggestion

Stephane Ducasse-3
What I would like is to extend pillar with a special environment 

[[[testable=5
3+ 2
]]]

and also 
[[[screenshot: 10@200 named: 'browserOpen'
Browser open
]]]

Now I need help on pillar. 

Stef



On Thu, May 25, 2017 at 3:57 PM, Stephane Ducasse <[hidden email]> wrote:
What I'm doing is 
- extracting a subset of pillar
- doc + renderer  
- so that we can use it in the image. 
Now kasper did a first version (in the repository and if people want to have a look it will help)
- now I'm remaving the dependency on magritte.

Stef

On Thu, May 25, 2017 at 2:03 PM, Ben Coman <[hidden email]> wrote:
Nice idea.  I've seen vague discussion about getting Pillar into the
standard image for documentation.
Perhaps it should be raised for consideration for Pharo 7?

Actually you stimulate my thoughts that the Help file might be a
better place for such snippets,
so they are always with the image, and don't need to be retyped.  Any
objections?

cheers -ben

On Thu, May 25, 2017 at 4:00 PM, K K Subbu <[hidden email]> wrote:
> Ben,
>
> I think there is a deeper need here. Writing good document is hard and
> keeping it in sync with code is harder still.
>
> A book/booklet separates content from the code and being frozen in time
> faces obsolescence. I would prefer to see a guidebook framework in Pharo
> that every package author can use to create a simple narrative on its
> features. Package authors and consumers have an incentive to keep the code
> and content in sync. If an Object is a recursion on the notion of a
> computer, why not provide, say a Note, as a recursive simplification of a
> book?
>
> The framework could be on the lines of Plugins, Tests. E.g.
>
>    Package-Core
>    Package-Plugins
>    Package-Tests
>    *Package-Guide*
>
> The guide framework should support active code (say to pop the source code
> for a method), active links to guides on which this package depends,
> automatic generation of table of contents, index of class references. Most
> of features already exists in Pharo but spread all over. They need a home.
>
> A package could also extend this basic framework with features (e.g. PDF
> package could export articles to PDF, Zinc could generate HTML).
>
> Regards .. Subbu
>
>
> On Thursday 25 May 2017 07:03 AM, Ben Coman wrote:
>>
>> I've seen a few requests for short bits of code to use in playground for
>> a demo presentation.  I wonder if it would be good to have a booklet to
>> gather these - seeded with Sven's excellent article...
>> https://medium.com/concerning-pharo/elegant-pharo-code-bb590f0856d0
>>
>> It could include the recent meta-programming scripts like searching for
>> all class instance variables starting with a capital letter.
>>
>> The book might be named "Snippets", in a format presentable to laser
>> print on-site - something physical for attendees to take away with them
>> to quick demo to others back in their office.
>>
>> I can take the lead in setting it up.  Anyone remember any relevant
>> posts in our archives?
>>
>> cheers -ben
>
>
>



Reply | Threaded
Open this post in threaded view
|

Re: Booklet suggestion

Ben Coman
In reply to this post by askoh


On Thu, May 25, 2017 at 9:32 PM, askoh <[hidden email]> wrote:
You gave me an idea.

Since Test Driven Design insists all tests passes before release, we can
piggy back on that by insisting Tutorials, Demos, Examples be tests that
must pass before release. Can we design Tutorials, Demos, Examples like
tests? I think so.

So TDDoc?

cheers -ben
Reply | Threaded
Open this post in threaded view
|

Re: Booklet suggestion

Ben Coman
In reply to this post by Stephane Ducasse-3


On Thu, May 25, 2017 at 9:59 PM, Stephane Ducasse <[hidden email]> wrote:
What I would like is to extend pillar with a special environment 


I had the same thought for a long time, but its sunk lower on my list. 
 
[[[testable=5
3+ 2
]]]

and also 
[[[screenshot: 10@200 named: 'browserOpen'
Browser open
]]]

Maybe something like... 
[[[ window := Browser openSized: 10@200.
window saveSnapshotAs: 'browserOpen'
]]]

cheers -ben
 

Now I need help on pillar. 

Stef



On Thu, May 25, 2017 at 3:57 PM, Stephane Ducasse <[hidden email]> wrote:
What I'm doing is 
- extracting a subset of pillar
- doc + renderer  
- so that we can use it in the image. 
Now kasper did a first version (in the repository and if people want to have a look it will help)
- now I'm remaving the dependency on magritte.

Stef

On Thu, May 25, 2017 at 2:03 PM, Ben Coman <[hidden email]> wrote:
Nice idea.  I've seen vague discussion about getting Pillar into the
standard image for documentation.
Perhaps it should be raised for consideration for Pharo 7?

Actually you stimulate my thoughts that the Help file might be a
better place for such snippets,
so they are always with the image, and don't need to be retyped.  Any
objections?

cheers -ben

On Thu, May 25, 2017 at 4:00 PM, K K Subbu <[hidden email]> wrote:
> Ben,
>
> I think there is a deeper need here. Writing good document is hard and
> keeping it in sync with code is harder still.
>
> A book/booklet separates content from the code and being frozen in time
> faces obsolescence. I would prefer to see a guidebook framework in Pharo
> that every package author can use to create a simple narrative on its
> features. Package authors and consumers have an incentive to keep the code
> and content in sync. If an Object is a recursion on the notion of a
> computer, why not provide, say a Note, as a recursive simplification of a
> book?
>
> The framework could be on the lines of Plugins, Tests. E.g.
>
>    Package-Core
>    Package-Plugins
>    Package-Tests
>    *Package-Guide*
>
> The guide framework should support active code (say to pop the source code
> for a method), active links to guides on which this package depends,
> automatic generation of table of contents, index of class references. Most
> of features already exists in Pharo but spread all over. They need a home.
>
> A package could also extend this basic framework with features (e.g. PDF
> package could export articles to PDF, Zinc could generate HTML).
>
> Regards .. Subbu
>
>
> On Thursday 25 May 2017 07:03 AM, Ben Coman wrote:
>>
>> I've seen a few requests for short bits of code to use in playground for
>> a demo presentation.  I wonder if it would be good to have a booklet to
>> gather these - seeded with Sven's excellent article...
>> https://medium.com/concerning-pharo/elegant-pharo-code-bb590f0856d0
>>
>> It could include the recent meta-programming scripts like searching for
>> all class instance variables starting with a capital letter.
>>
>> The book might be named "Snippets", in a format presentable to laser
>> print on-site - something physical for attendees to take away with them
>> to quick demo to others back in their office.
>>
>> I can take the lead in setting it up.  Anyone remember any relevant
>> posts in our archives?
>>
>> cheers -ben
>
>
>




Reply | Threaded
Open this post in threaded view
|

Re: Booklet suggestion

philippeback
In reply to this post by Ben Coman
WebDoc used to work in 3.0

Didn't loaded it since.

This is doing things like this: 




Phil

On Thu, May 25, 2017 at 2:03 PM, Ben Coman <[hidden email]> wrote:
Nice idea.  I've seen vague discussion about getting Pillar into the
standard image for documentation.
Perhaps it should be raised for consideration for Pharo 7?

Actually you stimulate my thoughts that the Help file might be a
better place for such snippets,
so they are always with the image, and don't need to be retyped.  Any
objections?

cheers -ben

On Thu, May 25, 2017 at 4:00 PM, K K Subbu <[hidden email]> wrote:
> Ben,
>
> I think there is a deeper need here. Writing good document is hard and
> keeping it in sync with code is harder still.
>
> A book/booklet separates content from the code and being frozen in time
> faces obsolescence. I would prefer to see a guidebook framework in Pharo
> that every package author can use to create a simple narrative on its
> features. Package authors and consumers have an incentive to keep the code
> and content in sync. If an Object is a recursion on the notion of a
> computer, why not provide, say a Note, as a recursive simplification of a
> book?
>
> The framework could be on the lines of Plugins, Tests. E.g.
>
>    Package-Core
>    Package-Plugins
>    Package-Tests
>    *Package-Guide*
>
> The guide framework should support active code (say to pop the source code
> for a method), active links to guides on which this package depends,
> automatic generation of table of contents, index of class references. Most
> of features already exists in Pharo but spread all over. They need a home.
>
> A package could also extend this basic framework with features (e.g. PDF
> package could export articles to PDF, Zinc could generate HTML).
>
> Regards .. Subbu
>
>
> On Thursday 25 May 2017 07:03 AM, Ben Coman wrote:
>>
>> I've seen a few requests for short bits of code to use in playground for
>> a demo presentation.  I wonder if it would be good to have a booklet to
>> gather these - seeded with Sven's excellent article...
>> https://medium.com/concerning-pharo/elegant-pharo-code-bb590f0856d0
>>
>> It could include the recent meta-programming scripts like searching for
>> all class instance variables starting with a capital letter.
>>
>> The book might be named "Snippets", in a format presentable to laser
>> print on-site - something physical for attendees to take away with them
>> to quick demo to others back in their office.
>>
>> I can take the lead in setting it up.  Anyone remember any relevant
>> posts in our archives?
>>
>> cheers -ben
>
>
>


Reply | Threaded
Open this post in threaded view
|

Re: Booklet suggestion

K K Subbu
In reply to this post by Ben Coman
On Thursday 25 May 2017 05:33 PM, Ben Coman wrote:
> Actually you stimulate my thoughts that the Help file might be a
> better place for such snippets,
> so they are always with the image, and don't need to be retyped.  Any
> objections?

None. You could gather these under Help->Quick Guide or Help->Tips with
a pointer to a larger collection.

Regards .. Subbu