On 23 November 2012 15:23, Camillo Bruni <[email protected]> wrote: > > On 2012-11-23, at 10:56, Igor Stasenko <[email protected]> wrote: > >> On 23 November 2012 13:57, dimitris chloupis <[email protected]> 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.
