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

[Ofri Wolfus]

Like all things in the open source community, this won't happen if  
people don't feel like doing it. Therefor, I suggest doing SEE  
sessions and have people document one class at a time together. This  
way we won't feel overloaded with the huge amounts of code that needs  
docs, and it's much more fun (and efficient) to work together. I  
think our changelogs already proved this works :)

- Ofri

- - - - - - - - - - - - - - - - - - -
http://www.dpompa.com
- - - - - - - - - - - - - - - - - - -


On 02/08/2007, at 15:32, Chris Forsythe wrote:

> 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
>>
>>
>
>
> _______________________________________________
> Adium-devl mailing list
> Adium-devl at adiumx.com
> http://adiumx.com/mailman/listinfo/adium-devl_adiumx.com

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://adium.im/pipermail/devel_adium.im/attachments/20070802/e2fd9611/attachment-0001.html>