[interfacekit] Re: Application Kit Tech Lead

Ithamar,

I'm glad you brought this stuff up (formatting interface specs) because 
I'm currently wrestling with this myself.  I've been reimplementing 
BArchivable & Co. to act as an example, but I've gotten sort of stuck on 
exactly where the dividing line between functional/interface spec and 
technical spec is and how it all relates to a) making it relatively easy 
to use what the BeBook already provides, b) making it relatively easy to 
create/maintain the OBOS version of the BeBook and c) making it easy on 
the devs so they'll actually complete and maintain the docs.  So!  I'm 
happy to hear whatever ideas you have concerning this.  My bullet-items 
thus far:

* Keep as much of the documentation in source as possible (as opposed to 
stand-alone documents)
* Re-use as much of the current BeBook material as possible
* Make extraction of documentation as painless and automatic as possible

Ideally, Dan Reinhold could do a cvs update, run an extraction tool, and 
publish the latest version of the docs.  Something that takes 10 or 15 
minutes, so we can have up-to-date docs once a week (at least).  If we 
get something nice worked out, we could pass it along to the entire team 
as a proposed standard for the whole project.

BTW, in addition to my BArchivable work, I have a ton of stuff from 
Frans van Nispen (sp?) just waiting to get checked in -- I'm holding off 
because I want to be able to assign the documentation work as soon as 
it's in, which I can't do until the format is worked out =P.

Glad you like the website; once we get this documentation issue hammered 
out, I'm going to finish up the tools for managing the site content and 
then convince Dan that he should let us generate our own content for the 
IK team page. =)

e

>Hi Erik,
>
>Yeah, this is only a few hours later, I know :) I've been looking at 
>the mailing list archives and I'm impressed :) I'm really willing to 
>take up the lead for the App Kit, but could you give me some small 
>samples from your interface specs? I've got some ideas of my own, but 
>want us to keep roughly in the same format....
>
>Just saw the stuff @ your website, nice compilation :)
>
>Please send me some samples, so I know what to create and how 
>roughly....
>
>Regards,
>
>Ithamar.

Data is not information, and information is not knowledge: knowledge is 
not understanding, and understanding is not wisdom.
        - Philip Adams

Other related posts: