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

[Chris Forsythe]

Does anyone have the log of where I described the history of Adium in  
irc? That would be a good starting point for some of this I think.

Eric, ping me when you're available, let's start on the policy  
documentation asap, we don't need to wait for 1.3.

Chris

On Aug 2, 2007, at 3:15 AM, Eric Richie wrote:

> 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
>
>