[Adium-devl] Documentation (aka 'Community Building')

[Eric Richie]

First off I'd like to say thanks to Chris for pointing out the Poisonous
People video.  I found it quite enlightening in spots since Adium was my
first and is still my main connection with the open source community at
large.  

That being said, I too have since consumed the Kool-Aide and I am very much
in favor of getting some more documentation out there.  The discussion
earlier was about documenting the code itself, but I think we need to go
beyond that and also document some of our policies and procedures.  In fact
I feel so strongly about this that I'd like to suggest the idea that maybe
along with working on the crash reports for 1.3 that we also make
documenting what we have (both code AND procedural) a priority rather than
just an "as we get around to/feel like it" activity.

There have been several instances recently where I was working on something
and had to take time out to bug Evan or David about a coding issue (I still
can't for the life of me figure out all the various plists associated with
prefs and their defaults and where they all go) or talk to Chris about how I
should handle something.  While I know that it's good to ask for help with
things and that they don't mind helping, it also takes time to answer them.
This time might be better spent doing something else.

My point is that a lot of these recent issues (to continue with my personal
example) could have been resolved if there were better documentation all
around.

The other issue that this creates is an entry barrier for people that might
want to help us out.  There are a lot of people who may be dying to lend a
hand but don't feel comfortable enough to come right out and ask for help.
These people would also be greatly benefited by the ability to actually look
up the answers to their questions.  Not to mention SoC students who may come
in knowing little or nothing about our codebase to begin with.

I know this is starting to become quite long but I'm realizing more and more
the importance of doing things the RIGHT WAY.  I am certainly willing to
help out with this effort wherever I can.  I'd also like to suggest that
once we get some procedural things documented (for instance how we'd like
the code itself to be documented [even if it's just a link to a page of best
practices]) that maybe we could offer some sort of a training session for
people that might want to contribute to the code documentation efforts like
we had done last year for tickets.

I hope that I'm preaching to the choir but I'd like to help do my part to
prod the effort along.  I think we owe it to ourselves and our community at
large to make some progress in these areas.  Good documentation has never
hurt anyone and will only be to the benefit of us and our beloved duck.

/steps down from the soapbox.

-Eric