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

[Augie Fackler]

Google docs works great for collaborative document editing like this  
- at work, we've used it for team-written design docs.
Augie

On Aug 2, 2007, at 12:50 PM, Eric Richie wrote:

> The other option would be to handle it a little more informally and  
> mention
> on #adium-devl that you're about to do X and post a link for others  
> to join
> in (like we often do with the changelog).  Only problem with that  
> would be
> that it's spur of the moment and someone may want to help but isn't  
> on irc
> right then.  For that reason alone, Chris might have a point about  
> trying to
> gather up a group to do it on the list.
>
> -Eric
>
>
> On 8/2/07 10:39 AM, "Chris Forsythe" <chris at growl.info> wrote:
>
>> Unfortunately SEE can only handle so many connections, depending on
>> latency and network speed it can vary. This will need to not be  
>> put on
>> the wiki for this reason, unless we want to tempt fates there.
>>
>> I would suggest that anyone who is interested to speak out on the  
>> list,
>> and maybe we could setup an informal group of some kind within the
>> mailing list itself. I don't know of a good way to do this.
>>
>> Chris
>>
>>
>> Matt Handley wrote:
>>
>>
>>> I think SubEthaEdit is a great idea. How will we know where to  
>>> connect
>>> to work on this? Some wiki page?
>>>
>>> Matt
>>>
>>> On 8/2/07, Ofri Wolfus <ofri.wolfus at gmail.com> wrote:
>>>
>>>
>>>> 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
>
>
>
> _______________________________________________
> Adium-devl mailing list
> Adium-devl at adiumx.com
> http://adiumx.com/mailman/listinfo/adium-devl_adiumx.com