Developers Documentation (was:A few questions to the developers)

[max]

The wiki documentation for developers is, at the moment .... well ... a little substandard. What can we do? anything we can contribute?

what I'dbe particularlyinterested in

* any written matter on the architecture of OpenGoo?
* Is there any documentation on the database relationships etc. ?

If I remember correctly I read somewhere OGOO started as a student project - so there's probably at least a diploma thesis somewhere?

I'd volunteer to put something online if you drop me some details.

[ignacio]

Unfortunately, the documentation for the student project is in Spanish, outdated and not too in-depth. But we would really appreciate your help. Would you like to lead the process of writing this docs? You can start with a skeleton of what you would like the docs to contain, like a table of contents, and we will start filling it with what each one can contribute. What do you think?

[max]

Great! I'll be happy to.

I'll browse around a bit and talk with a few pros about what they believe would be essential documentation.
Shouldn' be too long a list. maybe five to ten chapters. Plus a few "nice-to-haves".
I'll then compile that under the documentation wiki and I'll post back here when I think it's ripe for a discussion.
Should be fun. I'm very pleased that you would like to paricipate!

[ignacio]

Wonderful!

[max]

Here's a first brain dump.

Before I proceed I'd like some feedback from you Gooroos on this.
Probably might make sense to drop into a little skype session sometime, that would probably help to rule out much of that clutter there quickly.

apart from that I'm slightly fuzzy whether to discuss those documentation-related things here or rather right inside the wiki. I'd say: If it can't be annotated into a single line of text on the wiki then it should probably go into a thread in this forum here. (Do you know if the wiki sends out email notifications? I believe I can't subscribe manually to a page.)

If we should manage to go into much discussion then we could probably use a dedicated subform for that, later on…

best
m

[Stenner]

Excellent start! I think you're asking a lot of important questions in that document.

[max]

And here's a little service announcement:

If anyone has material that should go in there but not the time to do the languagework (texting) or the wikiwork (formatting, uploading etc), then just dump it over to me and I'll see if I can make it later on... supposedly you can use the PM function of this forum to contact me directly.

(I can't promise I'll be as enthusiastic for very long, so I recommend you better mail me soon! I'm always busy!)

m

[carlos]

Hi max,,

First of all,,, what a great initiative! I was planning on building a simple help section for developers but upon seeing what you have laid out in your "brain dump", it seems there are more points to cover than what I initially thought  .

Perhaps it would be a good idea to build upon what you have already written, we could probably work directly in the wiki entry, and discuss larger issues in the forum. I won't be able to work much on it today but probably by monday I might be able to upload and complete many of the points you mentioned.

I'll notify you once I have made any changes,, thanks!

[max]

hey, I was just beginning a reply to myself when your reply came in…

Nice to hear you like my endeavour. Actually I just want to become operational myself to get into writing a few hacks. So all these questions are mere by-products...

As another baby step I've just fed the whole OpenGoo package through phpDocumentor, an automated documentation tool.
It took my poor little laptop about an hour but I find the result is rather pleasant.

unfortunately it's 4 MB zipped so I can neither upload it to the dokuwiku (where it belongs) nor to this forum.

Maybe one of you admins could lift the upload-limit a bit? 2M is really not that much

In the meantime I've actually found myself putting up a google site to host that single file… Here you go.

[max]

More baby-step niceties… here's an annotatable list of All 3000+ files and directories in OpenGoo 1.3.1.

we could add some comments about units there now and then. Might make a nice point of reference. Unless of course this info was included in the modules themselves already. However, that isn't always the case (yet).

So the current release codename is "matambrito"? mjam mjam.

[carlos]

Hi max,, I just wanted to post an update, I was planning as I said on working on the wiki this weekend, but I didn't have the chance to sit down and work on it, so I'll see if I can do it today when I get back home.

I was checking on the output of phpDocumentor you just posted,, this is a good idea, I like the way the info gets presented. It would be interesting to see how phpDocumentor works with the internal comments. I saw that for example in the class trees, the models do not appear and there is an important hierarchy there, and upon further checking I saw they were not recognized as classes. We could also perhaps run phpDocumentor on a subset of the php files instead of running it on the whole project,,, for example, we could exclude the following files:

- All the language definitions
- Template files in application/views?
- Some common libraries such as the Zend framework.. on another note, these could be removed altogether, as they were used for testing search using Lucene, which isn't used or supported now.

this might improve the phpDocumentor processing time , besides making the info simpler and more useful or relevant. We should also work harder with the internal documentation as it is an aspect of development we have been overlooking for some time now .

Anyway, thanks for your help max!,, i really liked the phpDocumentor idea

[max]

Hi Carlos,

good to hear.

to start, I don't know if there might be a better documentation tool around (see this comparison. Their marketing blurb goes "phpDocumentor is the world standard auto-documentation tool for PHP".

AFAIK in order to omit a module from being parsed it must contain the tag "@access private" within a DocBlock.  I'll see if there is another possibility folders etc.

I totally second your opinion that the code documentation could be better. Automatic documentation is certainly useful for that; but obviously all of the developers need to embrace that functionality then. I don't know how you guys are structured and if this is feasible. If yes, I can probably help you with those documentation tasks.

Then we need someone to put it on your server.

And thinking of that, doesn't sourceforge offer a tool for automatic documentation…? hmmm. apparently not.

So one suggestion: Release the documentation as it is right now to some server, then make all developers read & embrace the tagging mechanism - then create a beautiful new set of documents after the next release?