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