Essential Documentation

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

Essential Documentation

julius
CONTENTS DELETED
The author has deleted this message.
Reply | Threaded
Open this post in threaded view
|

Re: Essential Documentation

Clément Béra
General documentation on all the base frameworks is present in the Pharo by example book. You can download it for free here: http://pharobyexample.org/versions/PBE1-2009-10-28.pdf
Or here for the updated version:

For frameworks like voyage, the documentation is available in another book which can also be downloaded for free:
Chapter 11 is about Voyage


On Fri, Sep 23, 2016 at 6:16 PM, julius <[hidden email]> wrote:
Probably this is a very beginners question but is there a documentation
online
or within the Pharo image for all the base-framework components like all
collections, Morphic, Numbers and so on?

I know Pharo uses a lot the 'see and discover yourself' approach but
sometimes,
especially for beginners it would be nice to have a documentation for most
classes
and also have programming guides. Coming from macOS and iOS development I
think about something like Swift or Objective-C has. For example you have
every
class there documented but also you have programming guides for how to draw
graphics. It would be really helpful to have somthing like that for example
for
Voyage (maybe it's there but I did not found it).

Thanks for helping me out!
Julius



--
View this message in context: http://forum.world.st/Essential-Documentation-tp4916861.html
Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.


Reply | Threaded
Open this post in threaded view
|

Re: Essential Documentation

SergeStinckwich
In reply to this post by julius
On Fri, Sep 23, 2016 at 6:16 PM, julius <[hidden email]> wrote:

> Probably this is a very beginners question but is there a documentation
> online
> or within the Pharo image for all the base-framework components like all
> collections, Morphic, Numbers and so on?
>
> I know Pharo uses a lot the 'see and discover yourself' approach but
> sometimes,
> especially for beginners it would be nice to have a documentation for most
> classes
> and also have programming guides. Coming from macOS and iOS development I
> think about something like Swift or Objective-C has. For example you have
> every
> class there documented but also you have programming guides for how to draw
> graphics. It would be really helpful to have somthing like that for example
> for
> Voyage (maybe it's there but I did not found it).

Yes I agree with the fact to have all classes/methods documented.
Can you contribute in that direction ?

--
Serge Stinckwich
UCBN & UMI UMMISCO 209 (IRD/UPMC)
Every DSL ends up being Smalltalk
http://www.doesnotunderstand.org/

Reply | Threaded
Open this post in threaded view
|

Re: Essential Documentation

Sven Van Caekenberghe-2
In reply to this post by julius
Hi Julius,

Have a look at http://books.pharo.org

These should certainly get you started.

Sven

> On 23 Sep 2016, at 18:16, julius <[hidden email]> wrote:
>
> Probably this is a very beginners question but is there a documentation
> online
> or within the Pharo image for all the base-framework components like all
> collections, Morphic, Numbers and so on?
>
> I know Pharo uses a lot the 'see and discover yourself' approach but
> sometimes,
> especially for beginners it would be nice to have a documentation for most
> classes
> and also have programming guides. Coming from macOS and iOS development I
> think about something like Swift or Objective-C has. For example you have
> every
> class there documented but also you have programming guides for how to draw
> graphics. It would be really helpful to have somthing like that for example
> for
> Voyage (maybe it's there but I did not found it).
>
> Thanks for helping me out!
> Julius
>
>
>
> --
> View this message in context: http://forum.world.st/Essential-Documentation-tp4916861.html
> Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.
>


Reply | Threaded
Open this post in threaded view
|

Re: Essential Documentation

julius
This post was updated on .
CONTENTS DELETED
The author has deleted this message.
Reply | Threaded
Open this post in threaded view
|

Re: Essential Documentation

stepharo
Have a look at the Spec video by Johan Fabry during the Pharo days on
youtube.


Le 23/9/16 à 23:32, julius a écrit :
> Thanks for you answers!
>
> I'm aware of the books on the pharo.org/documentation page. But for me that
> is not sufficient. I'm currently playing around while programming my fist own and
> unguided application. It will be quite simple, just a reminder application where
> notes can be added, removed, edited and all of them should trigger a notification when
> they are due. I plan to save all notes in a SQLite database, display is done with
> spec.

I'm interested by your result. It will be a nice example.

> While this is basic stuff I often have to go into the source and search for
> the correct messages to send and to see what kind of return objects I get. For
> example I wanted to use a SortedCollection as data structure for my notes
> (consisting of a
> string and a date) that should be ordered by date, so since this is not
> really described
> in the Pharo by Example book I looked at the implementation and searched
> online
>
> It would be definitely better to just have only or in the image a full
> documentation
> for SortedCollection which links to a full documentation of
> OrderedCollection.
This is call a class :). Now may be the class comments should be improved.
> I have to confess I didn't read Pharo in depth and Pharo for Enterpise yet
> but I also don't think its convenient to have all the books open and search there for
> documentation.
>
> Since I think a full searchable documentation would be very helpful
> especially for
> beginners and I definitely would like to have one I would be happy to
> contribute.
The books that are based on pillar are in pdf and html.
In the past we got a pharodoc but it was just the pharo comments on the web
so it was not really useful.
> Are there already some efforts toward it or does somebody has an idea how to
> accomplish
> that? Right now I imagine the best thing would be to have an automated
> workflow to read out
> the comments of the current release somehow and presenting them online.
> Maybe it would
> need to write a parser to get them well formatted (so that example code
> looks like code and so
> on). So if there is any way that I can contribute, I will do.
Point us to the point you have problems and tell us what are the class
comments that are poor.
Finish your project and write a little chapter. This will really help.

The chapter does not have to be complete.
Did you read the chapter of Sven on developing a reddit application in
10 classes?
Because having something like that with your project would be great and
I can participate if
you want.

> Best,
> Julius
>
>
>
> --
> View this message in context: http://forum.world.st/Essential-Documentation-tp4916861p4916904.html
> Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.
>
>


Reddit.pdf (363K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Essential Documentation

kilon.alios
In reply to this post by julius
The documentation of pharo currently is much better than documentation for open source projects of similar size. Do not expect full or large documentation with such small community or class comments.

"See and discover yourself" is the approach to coding at large because in most cases whether you have a popular or non popular language documentation will always be a problem because developers generally don't like to write documentation.

However the best documentation by large for pharo is this mailing list and the slack channel. For example when I was learning NBOpenGL i literally bombarded this mailing list with questions and all of them got answered in just a few hours. For 4 years now, non of my questions have been left unanswered and I am one of those people that have no hesitation at all asking stupid questions :D

The irony here is that even though developers don't like writing documentation they absolutely LOOOOOVEEEEE answering questions :D

so its also a nice trick to go in the forum of world.st , which basically takes the mailing list messages and present them as a forum and you can do search whatever you want.

http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

For Graphics , vector graphics, Roassal is probably the best choice if you want to visualize data and comes with nice documentation. Roassal uses Athens which is basically Cairo wrapped for Pharo which also has some documentation and some examples.


On Fri, Sep 23, 2016 at 7:22 PM julius <[hidden email]> wrote:
Probably this is a very beginners question but is there a documentation
online
or within the Pharo image for all the base-framework components like all
collections, Morphic, Numbers and so on?

I know Pharo uses a lot the 'see and discover yourself' approach but
sometimes,
especially for beginners it would be nice to have a documentation for most
classes
and also have programming guides. Coming from macOS and iOS development I
think about something like Swift or Objective-C has. For example you have
every
class there documented but also you have programming guides for how to draw
graphics. It would be really helpful to have somthing like that for example
for
Voyage (maybe it's there but I did not found it).

Thanks for helping me out!
Julius



--
View this message in context: http://forum.world.st/Essential-Documentation-tp4916861.html
Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.

Reply | Threaded
Open this post in threaded view
|

Re: Essential Documentation

Offray Vladimir Luna Cárdenas-2
In reply to this post by julius
Julius,

On the interactive documentation front I'm working in a project called
Grafoscopio. Now it has a translated English main page at [1]. Is not
for writing code documentation, but for writing tutorials, books and
alike that mix prose, code, data and visualizations, think in something
similar to Mathematica or Jupyter notebooks, but with an outline
structure to hold a complete book (instead of the common pile of files
inside folders approach) or support complex explorative
writing/computing. See an example of this at [2]. It can also produce
pdf outputs (via pandoc), like the two draft documents at [3] and [4],
made in grafoscopio

[1] http://mutabit.com/grafoscopio/index.en.html
[2] http://mutabit.com/offray/blog/en/entry/panama-papers-1
[3]
http://mutabit.com/repos.fossil/grafoscopio/doc/tip/Docs/Es/Articulos/Libertadores/bootstrapping-objeto-investigacion.pdf
[4] http://mutabit.com/repos.fossil/piamed/doc/tip/Libro/libro.pdf

My approach to build such app was to start with the simplest prototype,
using Glamorous Toolkit [5] and reading the useful chapters of Deep into
Pharo [6] about Glamour (chap. 10), Files with the FileSystem (chap. 3)
Versioning Your Code with Monticello (chap 7), Gofer: Scripting Package
Loading (chap 8), the paper on ston [7] and then the Agile Visualization
Book [8] and ask questions in this mailing list. I skipped the Pharo by
example book, because the game building approach was not what I
wanted/needed, so I filled a lot of gaps in my knowledge with the recent
Pharo MOOC [9].

[5] http://gtoolkit.org/
[6] http://deepintopharo.com/
[7] https://github.com/svenvc/ston/blob/master/ston-paper.md
[8] http://agilevisualization.com/
[9] http://files.pharo.org/mooc/

As you can see my learning process was problem/project oriented and that
was the path I followed to build my "essential documentation". Being the
only Smalltalker active in my country (AFAIK) was kind of difficult, but
in the virtual space you can find a community that is welcoming,
proactive and responsive most of the time. Now I'm trying to enlarge the
community by serving a different public (non-programmers like me) that
are interested in data storytelling, visualization and (h)ac(k)tivism (
journalists, non computer science academics, activist, philosophers, etc).

So even if Pharo doesn't have the classical documentation, the community
around it, the documentation and the environment, can support
alternative learning paths, driven by exploration and problem solving
and I hope you can find a place and path here for your project.

Welcome here Julius,

Offray


On 23/09/16 11:16, julius wrote:

> Probably this is a very beginners question but is there a documentation
> online
> or within the Pharo image for all the base-framework components like all
> collections, Morphic, Numbers and so on?
>
> I know Pharo uses a lot the 'see and discover yourself' approach but
> sometimes,
> especially for beginners it would be nice to have a documentation for most
> classes
> and also have programming guides. Coming from macOS and iOS development I
> think about something like Swift or Objective-C has. For example you have
> every
> class there documented but also you have programming guides for how to draw
> graphics. It would be really helpful to have somthing like that for example
> for
> Voyage (maybe it's there but I did not found it).
>
> Thanks for helping me out!
> Julius
>
>
>
> --
> View this message in context: http://forum.world.st/Essential-Documentation-tp4916861.html
> Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.
>
>


Reply | Threaded
Open this post in threaded view
|

Re: Essential Documentation

Offray Vladimir Luna Cárdenas-2
In this problem/project custom learning path now I'm learning better
packaging and exploring the Spec-Glamour interface.

Cheers,

Offray


On 26/09/16 19:40, Offray Vladimir Luna Cárdenas wrote:

> Julius,
>
> On the interactive documentation front I'm working in a project called
> Grafoscopio. Now it has a translated English main page at [1]. Is not
> for writing code documentation, but for writing tutorials, books and
> alike that mix prose, code, data and visualizations, think in
> something similar to Mathematica or Jupyter notebooks, but with an
> outline structure to hold a complete book (instead of the common pile
> of files inside folders approach) or support complex explorative
> writing/computing. See an example of this at [2]. It can also produce
> pdf outputs (via pandoc), like the two draft documents at [3] and [4],
> made in grafoscopio
>
> [1] http://mutabit.com/grafoscopio/index.en.html
> [2] http://mutabit.com/offray/blog/en/entry/panama-papers-1
> [3]
> http://mutabit.com/repos.fossil/grafoscopio/doc/tip/Docs/Es/Articulos/Libertadores/bootstrapping-objeto-investigacion.pdf
> [4] http://mutabit.com/repos.fossil/piamed/doc/tip/Libro/libro.pdf
>
> My approach to build such app was to start with the simplest
> prototype, using Glamorous Toolkit [5] and reading the useful chapters
> of Deep into Pharo [6] about Glamour (chap. 10), Files with the
> FileSystem (chap. 3) Versioning Your Code with Monticello (chap 7),
> Gofer: Scripting Package Loading (chap 8), the paper on ston [7] and
> then the Agile Visualization Book [8] and ask questions in this
> mailing list. I skipped the Pharo by example book, because the game
> building approach was not what I wanted/needed, so I filled a lot of
> gaps in my knowledge with the recent Pharo MOOC [9].
>
> [5] http://gtoolkit.org/
> [6] http://deepintopharo.com/
> [7] https://github.com/svenvc/ston/blob/master/ston-paper.md
> [8] http://agilevisualization.com/
> [9] http://files.pharo.org/mooc/
>
> As you can see my learning process was problem/project oriented and
> that was the path I followed to build my "essential documentation".
> Being the only Smalltalker active in my country (AFAIK) was kind of
> difficult, but in the virtual space you can find a community that is
> welcoming, proactive and responsive most of the time. Now I'm trying
> to enlarge the community by serving a different public
> (non-programmers like me) that are interested in data storytelling,
> visualization and (h)ac(k)tivism ( journalists, non computer science
> academics, activist, philosophers, etc).
>
> So even if Pharo doesn't have the classical documentation, the
> community around it, the documentation and the environment, can
> support alternative learning paths, driven by exploration and problem
> solving and I hope you can find a place and path here for your project.
>
> Welcome here Julius,
>
> Offray
>
>
> On 23/09/16 11:16, julius wrote:
>> Probably this is a very beginners question but is there a documentation
>> online
>> or within the Pharo image for all the base-framework components like all
>> collections, Morphic, Numbers and so on?
>>
>> I know Pharo uses a lot the 'see and discover yourself' approach but
>> sometimes,
>> especially for beginners it would be nice to have a documentation for
>> most
>> classes
>> and also have programming guides. Coming from macOS and iOS
>> development I
>> think about something like Swift or Objective-C has. For example you
>> have
>> every
>> class there documented but also you have programming guides for how
>> to draw
>> graphics. It would be really helpful to have somthing like that for
>> example
>> for
>> Voyage (maybe it's there but I did not found it).
>>
>> Thanks for helping me out!
>> Julius
>>
>>
>>
>> --
>> View this message in context:
>> http://forum.world.st/Essential-Documentation-tp4916861.html
>> Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.
>>
>>
>
>
>


Reply | Threaded
Open this post in threaded view
|

Re: Essential Documentation

julius
CONTENTS DELETED
The author has deleted this message.
Reply | Threaded
Open this post in threaded view
|

Re: Essential Documentation

Offray Vladimir Luna Cárdenas-2
Hi,


On 27/09/16 09:17, julius wrote:
> Thanks for all replies and the good advice. Grafoscopio looks impressive and
> very interesting!

Thanks. There is still a lot of work to be done and code to be improved,
but is getting more maturity. Still I would like to make some videos
showing the new characteristics on sharing and storing playgrounds
inside a notebook.

> After working more and more with Pharo I see and
> understand the approach to documentation better I think. So my next steps
> will be finishing the application I'm writing and documenting that, also if
> I see class comments that are hard to understand I will report them, maybe
> even try to improve them myself.

That would be very worthy.

Cheers,

Offray


Reply | Threaded
Open this post in threaded view
|

Re: Essential Documentation

stepharo
In reply to this post by julius


Le 27/9/16 à 17:17, julius a écrit :
> Thanks for all replies and the good advice. Grafoscopio looks impressive and
> very interesting! After working more and more with Pharo I see and
> understand the approach to documentation better I think. So my next steps
> will be finishing the application I'm writing and documenting that, also if
> I see class comments that are hard to understand I will report them, maybe
> even try to improve them myself.

super.
I want to have a look at your application. I can do a code review if you
like.
>
> I'm thinking a lot about how to improve the programming experience and one
> thing I came up with was, that maybe showing the comment of a message while
> having the autocompletion dialog open or when selecting it in the code
> editor would help to grasp the frameworks faster. Since I still don't know
> much about the whole system: would that be hard to implement?
If would be good.
The autocompletion is a bit rusty code but getting the comments of a method
is easy check compiledMethod I think that there is one comment or
getComment or firstcomment
method.

>
> Best,
> Julius
>
>
>
> --
> View this message in context: http://forum.world.st/Essential-Documentation-tp4916861p4917224.html
> Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.
>
>