yarffaJ nalA (jnala) wrote in lj_dev,
yarffaJ nalA

Do we need more server documentation?

In a comment over on lj_biz, tribelessnomad wrote:
Incidentally, since you're one of the few people working closely with the source code, I hope you'll give serious thought to focusing on source-code documentation instead of end-user documentation. It isn't my place to tell
you what to do -- I just want to be sure you realize that source-code documentation is VERY much needed, and there's hardly anyone available to do it.

Do people perceive such a need? We have the protocol documentation (complete, clear), the schema browser (missing many descriptions, but usually evocative column names), and the source code (written in a high-level language, in a pretty clear style). There's also the server itself, which you can run and test against.

Basically, I found it pretty easy to jump in and start hacking once someone pointed me at the source and the schema. There was definitely a learning curve, but I'm not sure whether more docs would make a big dent in it. (Well, a complete set of schema descriptions would be nice, but Brad's working on that.) More importantly, I'm not sure whether that learning curve is actually posing a barrier to people with sufficient ability and desire to work on the code.

I dunno. It seems to me like we're better off writing new code and cleaning up existing code than writing about the code (and maintaining that writing across changes). What do other people think?

  • Post a new comment


    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded