[Pharo-project] Athens Documentation (was: Helping with Athens development)
On 23 November 2012 13:57, dimitris chloupis <thekilon@yahoo.co.uk> wrote:
Thank you Igor , this was the type of answer I wanted . Ok I think I will work first on documenting the code and creating a pdf that helps the user understand how to use Athens. After I gain a very good insight through documentation of how Athens works I start contributing code. I assume for documenting code (adding doc strings to methods missing them) files out and attaching them here will do or you want me to upload to my own project in ss3 ?
Well, i was thinking more about format which is available online. And because Athens documentation will absolutely require a lot of illustrations, i think best would be to use HTML for it. (or something which generates html ). Making a PDF out of it is not a big deal, isn't? Of course, this is not makes class/method comments less important. But i vote for online documentation first. Because most of people don't even understand the basic concepts of paths/contours and coordinate system.. and class comments are not really helpful for that. I wanna have something like Amber documentation: http://amber-lang.net/documentation.html Also, as for the starting point, what things we should describe there, i think OpenVG spec could serve as a guiding source. www.khronos.org/registry/vg/specs/openvg_1_0_1.pdf it contains a lot of material which we can reuse for starters: matrices, coordinate system, paths and path commands etc. So, for getting started we much decide what source format we should use. and where we will host it (as an early-term solution i propose to just create a project on github). And then first step would be to make a TOC :) -- Best regards, Igor Stasenko.
On 2012-11-23, at 10:56, Igor Stasenko <siguctua@gmail.com> wrote:
On 23 November 2012 13:57, dimitris chloupis <thekilon@yahoo.co.uk> wrote:
Thank you Igor , this was the type of answer I wanted . Ok I think I will work first on documenting the code and creating a pdf that helps the user understand how to use Athens. After I gain a very good insight through documentation of how Athens works I start contributing code. I assume for documenting code (adding doc strings to methods missing them) files out and attaching them here will do or you want me to upload to my own project in ss3 ?
Well, i was thinking more about format which is available online. And because Athens documentation will absolutely require a lot of illustrations, i think best would be to use HTML for it. (or something which generates html ). Making a PDF out of it is not a big deal, isn't?
yes! - presence in the web is very important for people coming from the outside. - in image documentation/examples are very important for development speed so yes, somthing like markdown can be easily converted to pdf, I use http://johnmacfarlane.net/pandoc/ regularly to compile my outline notes to nice pdfs ;)
Of course, this is not makes class/method comments less important. But i vote for online documentation first.
Online documents are mainly for, let's say, lazy users of your system, currently we're still in core development, so I would go for the things needed by programmers. That is Examples, Class Comments and maybe method comments. I am certainly a bit extreme on that, but I think investing time into examples that explain the design is wort more. Also for me this is more smalltalk. I hate reading prose text which is a fuzzy definition of something whereas I could read a nicely documented example and debug and learn it!
Because most of people don't even understand the basic concepts of paths/contours and coordinate system.. and class comments are not really helpful for that
I definitely agree on that (as we figured out with esteban, we were both not that solid on this topic). But examples are much better, much more interactive.
I wanna have something like Amber documentation: http://amber-lang.net/documentation.html
well I you focus on examples you could revive my old WebDoc thingy that will nicely format the source code and uses full markdown for all in-method comments.
Also, as for the starting point, what things we should describe there, i think OpenVG spec could serve as a guiding source.
www.khronos.org/registry/vg/specs/openvg_1_0_1.pdf
it contains a lot of material which we can reuse for starters: matrices, coordinate system, paths and path commands etc.
So, for getting started we much decide what source format we should use. and where we will host it (as an early-term solution i propose to just create a project on github).
Go for examples! I want to have the most interactive documentation possible! Otherwise, yes github + wiki is a low-resistance solution, though we should take care that we have the information as well in the image :)
And then first step would be to make a TOC :)
-- Best regards, Igor Stasenko.
I dont know if that is going to sound like a crazy idea or a difficult idea but here it goes. I agree with you that included documentation is probably much better than pdfs or htlm. Excuse me if that was not your point , but that is certainly a belief of mine. For my project Ephestos , I was thinking of creating a small morphic window that displays documentation 10 lines tops (no scrolling allowed) and has the ability to offer tutorials step by step. Very similar to ProfStef tutorial, I am a huge fan of learning like this coding. This is why I said I am very interested in how the onboard help system works on Pharo. For me ideally If I can expand Pharo help system so that it can do ProfStef like tutorials for Athens in a step by step process I think that people will benefit a lot more than a pdf or hltm that is a long read. Of course this help system expansion wont benefit only Athens user but it could be used for documenting anything inside Pharo. If I could integrate the help system with system browser that would be even better. I am open to any suggestions and criticism. ________________________________ From: Camillo Bruni <camillobruni@gmail.com> To: Pharo-project@lists.gforge.inria.fr Sent: Friday, 23 November 2012, 16:23 Subject: Re: [Pharo-project] Athens Documentation (was: Helping with Athens development) On 2012-11-23, at 10:56, Igor Stasenko <siguctua@gmail.com> wrote:
On 23 November 2012 13:57, dimitris chloupis <thekilon@yahoo.co.uk> wrote:
Thank you Igor , this was the type of answer I wanted . Ok I think I will work first on documenting the code and creating a pdf that helps the user understand how to use Athens. After I gain a very good insight through documentation of how Athens works I start contributing code. I assume for documenting code (adding doc strings to methods missing them) files out and attaching them here will do or you want me to upload to my own project in ss3 ?
Well, i was thinking more about format which is available online. And because Athens documentation will absolutely require a lot of illustrations, i think best would be to use HTML for it. (or something which generates html ). Making a PDF out of it is not a big deal, isn't?
yes! - presence in the web is very important for people coming from the outside. - in image documentation/examples are very important for development speed so yes, somthing like markdown can be easily converted to pdf, I use http://johnmacfarlane.net/pandoc/ regularly to compile my outline notes to nice pdfs ;)
Of course, this is not makes class/method comments less important. But i vote for online documentation first.
Online documents are mainly for, let's say, lazy users of your system, currently we're still in core development, so I would go for the things needed by programmers. That is Examples, Class Comments and maybe method comments. I am certainly a bit %xtreme on that, but I think investing time into examples that explain the design is wort more. Also for me this is more smalltalk. I hate reading prose text which is a fuzzy definition of something whereas I could read a nicely documented example and debug and learn it!
Because most of people don't even understand the basic concepts of paths/contours and coordinate system.. and class comments are not really helpful for that
I definitely agree on that (as we figured out with esteban, we were both not that solid on this topic). But examples are much better, much more interactive.
I wanna have something like Amber documentation: http://amber-lang.net/documentation.html
well I you focus on examples you could revive my old WebDoc thingy that will nicely format the source code and uses full markdown for all in-method comments.
Also, as for the starting point, what things we should describe there, i think OpenVG spec could serve as a guiding source.
www.khronos.org/registry/vg/specs/openvg_1_0_1.pdf
it contains a lot of material which we can reuse for starters: matrices, coordinate system, paths and path commands etc.
So, for getting started we much decide what source format we should use. and where we will host it (as an early-term solution i propose to just create a project on github).
Go for examples! I want to have the most interactive documentation possible! Otherwise, yes github + wiki is a low-resistance solution, though we should take care that we have the information as well in the image :)
And then first step would be to make a TOC :)
-- Best regards, Igor Stasenko.
On 23 November 2012 15:33, dimitris chloupis <thekilon@yahoo.co.uk> wrote:
I dont know if that is going to sound like a crazy idea or a difficult idea but here it goes. I agree with you that included documentation is probably much better than pdfs or htlm. Excuse me if that was not your point , but that is certainly a belief of mine.
For my project Ephestos , I was thinking of creating a small morphic window that displays documentation 10 lines tops (no scrolling allowed) and has the ability to offer tutorials step by step. Very similar to ProfStef tutorial, I am a huge fan of learning like this coding.
This is why I said I am very interested in how the onboard help system works on Pharo. For me ideally If I can expand Pharo help system so that it can do ProfStef like tutorials for Athens in a step by step process I think that people will benefit a lot more than a pdf or hltm that is a long read. Of course this help system expansion wont benefit only Athens user but it could be used for documenting anything inside Pharo.
If I could integrate the help system with system browser that would be even better. I am open to any suggestions and criticism.
yeah.. it would be interesting to go that way.. self example: [ do something with athens here ] description: ' okay, here you can see we're drawing things blah blah ' You can look at AthensDemoMorph as a prototype for that. Use: AthensDemoMorph new openInWorld inspect and in inspector you can switch between figures using 'self nextFigure' or 'self prevFigure' turning it into nice window with illustration alongside of text describing it, is not too hard. -- Best regards, Igor Stasenko.
On 23 November 2012 15:23, Camillo Bruni <camillobruni@gmail.com> wrote:
On 2012-11-23, at 10:56, Igor Stasenko <siguctua@gmail.com> wrote:
On 23 November 2012 13:57, dimitris chloupis <thekilon@yahoo.co.uk> wrote:
Thank you Igor , this was the type of answer I wanted . Ok I think I will work first on documenting the code and creating a pdf that helps the user understand how to use Athens. After I gain a very good insight through documentation of how Athens works I start contributing code. I assume for documenting code (adding doc strings to methods missing them) files out and attaching them here will do or you want me to upload to my own project in ss3 ?
Well, i was thinking more about format which is available online. And because Athens documentation will absolutely require a lot of illustrations, i think best would be to use HTML for it. (or something which generates html ). Making a PDF out of it is not a big deal, isn't?
yes! - presence in the web is very important for people coming from the outside. - in image documentation/examples are very important for development speed
so yes, somthing like markdown can be easily converted to pdf, I use http://johnmacfarlane.net/pandoc/ regularly to compile my outline notes to nice pdfs ;)
Of course, this is not makes class/method comments less important. But i vote for online documentation first.
Online documents are mainly for, let's say, lazy users of your system, currently we're still in core development, so I would go for the things needed by programmers. That is Examples, Class Comments and maybe method comments.
the problem is that many parts of it needs illustrations. it is better to see once, than hear many times. for instance, tell me if you can understand this: path can have many contours, a new contour start either from 'close' command or 'moveto' command which implicitly closes the current contour (for fills, but not for strokes). using multiple contours in path, you can create hollow shapes by defining intersecting shapes (per contour) with different winding (clockwise /counterclockwise).
I am certainly a bit extreme on that, but I think investing time into examples that explain the design is wort more. Also for me this is more smalltalk. I hate reading prose text which is a fuzzy definition of something whereas I could read a nicely documented example and debug and learn it!
Because most of people don't even understand the basic concepts of paths/contours and coordinate system.. and class comments are not really helpful for that
I definitely agree on that (as we figured out with esteban, we were both not that solid on this topic). But examples are much better, much more interactive.
I wanna have something like Amber documentation: http://amber-lang.net/documentation.html
well I you focus on examples you could revive my old WebDoc thingy that will nicely format the source code and uses full markdown for all in-method comments.
okay.. then (all) give me the list of examples what you wanna see.
Also, as for the starting point, what things we should describe there, i think OpenVG spec could serve as a guiding source.
www.khronos.org/registry/vg/specs/openvg_1_0_1.pdf
it contains a lot of material which we can reuse for starters: matrices, coordinate system, paths and path commands etc.
So, for getting started we much decide what source format we should use. and where we will host it (as an early-term solution i propose to just create a project on github).
Go for examples! I want to have the most interactive documentation possible! Otherwise, yes github + wiki is a low-resistance solution, though we should take care that we have the information as well in the image :)
There is some examples in AthensSurfaceExamples. also, Athens-Morphic is a good source of examples. you can look what drawnOn: method doing and compare it with drawOnAthensCanvas: method for same morph.
And then first step would be to make a TOC :)
-- Best regards, Igor Stasenko.
Of course, this is not makes class/method comments less important. But i vote for online documentation first.
Online documents are mainly for, let's say, lazy users of your system, currently we're still in core development, so I would go for the things needed by programmers. That is Examples, Class Comments and maybe method comments.
the problem is that many parts of it needs illustrations. it is better to see once, than hear many times.
for instance, tell me if you can understand this:
path can have many contours, a new contour start either from 'close' command or 'moveto' command which implicitly closes the current contour (for fills, but not for strokes).
using multiple contours in path, you can create hollow shapes by defining intersecting shapes (per contour) with different winding (clockwise /counterclockwise).
if I have an example I can run with the vey same text you wrote I understand everything! And I think with something like Esteban's athen workspace that should be fairly easy to achieve. basic contour examples ====================== - path with 1 contour - path with 2 contours - some fancy example with complex contours Hollow shapes ============= - start with a rect - start with a rect with another rect cut out => I have running code I can copy paste, that is worth more than some text I have to transform into a running model in my head... => no graphs needed, all your visualizations are running code examples!
I think that having a proftef ilke approach is the way to go + class comments So creating a library of example like in mondrian or roassal is the best way to give a chance to people to learn. stef
participants (4)
-
Camillo Bruni -
dimitris chloupis -
Igor Stasenko -
Stéphane Ducasse