[Chandler-dev] Re: More documentation about the repository?

[Markku Mielityinen]

Hello Andi,

Thank you for your quick reply.

Andi Vajda wrote:
>
> On Thu, 29 Jun 2006, Markku Mielityinen wrote:
>
>> This week I had some free time from my Chandler internationalization 
>> work, so I started to read all the documentation there is about 
>> Chandler (including those in 
>> http://chandler.osafoundation.org/docs/0.6/ and the text formatted 
>> documentation that there is in the source tree). I became interested 
>> in the repository and its design so I tried to find as much 
>> information about that as I could. The documents that I found 
>> explained clearly how to use the repository in parcels but contained 
>> less information about the actual design and implementation of the 
>> repository. When I was unable to find a good document about that, I 
>> started to browse the source codes, used a couple of days doing that 
>> but was unable to reach a really good understanding of how the 
>> repository works. I guess it was just the sheer amount of source code 
>> lines distributed in so many source files that kept me from seeing a 
>> clear hierarchy inside the code, which again prevented me from 
>> gaining a good understanding of the repository. Do you have any 
>> additional documentation about the repository, possible something 
>> that you keep to yourself because you feel that it is not ready for 
>> publication, that I could use to increase my understanding of the 
>> design.
>
> Sorry, I don't have any hidden documentation. Another source of 
> documentation you may not be aware of is the repository blog to which 
> I've been posting not so regularly since I'm not too aware of its 
> actual readership:
>     http://blogs.osafoundation.org/chandlerdb

No problem, the reason I asked is that I sometimes have such "work 
product" documents that are enough for my own use but that are less 
useful for others as they require some amount of prior knowledge of the 
matter that is being documented (I use them when I don't have enough 
time to do proper documentation or when documentation is not really 
needed). When I asked around for a repository document I was directed to 
the repository blog. I will certainly read it as my time table allows 
it. Still, my initial impression is that this approach has the same 
problem as the approach of reading the source code. You can see the 
trees but you cannot see the forest...

> I realize that this does not represent comprehensive design docs or 
> any such thing but it's a bunch of pretty accurate postings about some 
> repository features as I added them.
>
> There is quite a bit of epydoc (API documentation) in the source code. 
> Another thing to keep in mind is that the repository code is broken up 
> into two pieces: the python code in chandler/repository and the C code 
> (and some python too) in internal/chandlerdb. There is also a bunch of 
> epydoc in the C code which you can find here:
> http://svn.osafoundation.org/chandler/trunk/internal/chandlerdb/chandlerdb/__init__.py

Yes I am aware of this fact. In fact, this is one reason that makes 
reading the source code so difficult...

> And last but not least: anything about the repository you find on our 
> wiki is most likely either wrong or out of date. I don't use the wiki 
> at all. The chandlerdb blog is supposed play that role.
>
> Of course, if you have specific questions, feel free to ask either via 
> email to me or on the chandler-dev mailing list. If you have ideas 
> about specific blog posts I could add to the chandlerdb blog, 
> suggestions are welcome.

I will certainly do that.

Markku