OpenCore Software

I was reading Ra’s latest blog post and, curious about the work he’s been doing on remote authentication, glanced at the changelog of his branch.  I saw that he had added a few things which already existed in opencore: an API for getting information about a member, and an API for verifying a user’s credentials from a remote opencore server.  I’d added both of these things recently (in the past month or so) on the wordpress-sandbox branch, and they’d only just (in the past week or so) been merged to trunk, so it was very reasonable that Ra didn’t know about them — they might not even exist on his branch, depending on how recently he cut it from trunk.  Anyway, I emailed him to let him know about these two things so he could consider merging the duplicated functionality before going back to trunk.

But that got me thinking about why Ra hadn’t known about these things, and how he might have known about them.  Though I had written up a description of how to use them, I never emailed the dev list about them or anything, so he really only could have known about the additions if he had happened to see the commits where I made them or if he had happened to be watching the channel when I told Anil about my writeup. 

And then it occurred to me that this isn’t an isolated incident; we often don’t know what we’re all working on, what new features have been added, or how to use each others’ code.  In the same blog post, Ra said he was “pleased to find that we already had a nice HTTPMock object” in opencore, which IIRC Whit and I had put in there back in March(?) during the last stages of opencore<->tasktracker integration work.  And it’s not unique to opencore; just in the past week, Whit recently wrote that he was trying to understand how to use Cabochon, and Ian said he didn’t understand our build system.

I think there are a lot of things we can and need to do to work on this.  Here are my thoughts on it; I’m curious what everyone else thinks.  Whit has been encouraging us all to write more blog posts to improve our communication and keep our eye on the big picture.  More blog posts could also help us all get a better sense of what we’re working on and therefore what code is being written.  I don’t think that’s the whole answer, though.  More Bug Days will help, too, since they’ll help us transfer knowledge about code to each other in a fast and focused way.  I also think we should write more wiki pages like that opencore.api writeup — after all, a wiki page seems like the right medium for this sort of thing: publishing generally stable but occasionally changing information.  That will only work if we have a place or places to put them, though, or some way of collecting documentation pages like that.  (I know others exist, but I’m not sure where or what they are… it’s especially a problem for opencore documentation, since this project is so littered with random pages about OpenPlans and TOPP.)  And, in general, we need much better developer documentation — external docs, comments, tests, whatever — especially when creating a new feature or service.