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.