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.