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. 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. >
