Call for help: documentation
Jamis Buck
I fully acknowledge that. And I assume all the blame for it, too. I
want to do something about it, but I've been far, far (far!) too
swamped for the last six months to do more than acknowledge the need.
So, I'm pleading for your help. Here's what I'd like to happen:
1. I'd like one (maybe two) people to step forward, to volunteer to
coordinate the documentation effort. This person would ideally be
responsible for identifying what needs to be documented,
standardizing on a format for documentation, etc. They would work
with me to make sure it fits with my vision for Capistrano, but
mostly they would have a free reign to do what needs to be done.
2. I'd like as many people as possible to volunteer to submit
documentation. This would happen after the coordinator identified
what needs to be documented. People would then sign up to take on one
of the areas pending documentation. If no action occurs on it within
a month or so, that task would automatically become available again
for someone else to sign up for.
The documentation thus generated will be hosted at capify.org.
Thoughts? Volunteers? If you'd like to coordinate the documentation
effort, please email me directly, off-list. We'll see how many
volunteer, and I'll pick the "winner". :)
- Jamis
Kenneth Kalmer
see how things work, and how to get things done... I'm definitely not
one for coordinating the doc project, I just have too much on my
plate...
Best
--
Kenneth Kalmer
kenneth...@gmail.com
Folding@home stats
http://fah-web.stanford.edu/cgi-bin/main.py?qtype=userpage&username=kenneth%2Ekalmer
John Joseph Bachir
I'd like to put a vote in for the documentation being maintained via a
wiki. Now, don't get me wrong, I know we've all seen a lot of really
poorly organized and sloppy open source documentation wikis out there.
But I think that this problem could be easily solved by having a
dedicated wiki gardener, who only contributed (and enforced) structure
/ organization / categorization, within which the other documentation
contributors could work. I think that the person(s) described in point
1 in Jamis' email could fit into this role.
From anecdotal evidence I feel pretty strongly that effective
documentation needs to be a wiki. The Rails wiki is an example of
documentation that is poorly organized but still provides useful
answers in google searches. The prototype documentation is an example
of non-wiki documentation that is... limited.
Clearly, an ideal grand finalé for my statement would be an example of
a well-organized documentation wiki, but I can't think of one :-D
Anyone else have examples of good and bad documentation
implementations in various media?
John
--
John Joseph Bachir
http://lyceum.ibiblio.org <--- has poorly maintained documentation wiki :)
http://blog.johnjosephbachir.org
aim/yim/msn/jabber.org/gtalk: johnjosephbachir
713-494-2704
http://jjb.cc
Kevin Williams
> Anyone else have examples of good and bad documentation
> implementations in various media?
I think the RSpec docs are quite good. Those are done via webgen.
http://rspec.rubyforge.org
Jamis Buck
having a team of maintainers that are willing to spend a good deal of
their spare time just moderating. Wiki's are spam targets at the best
of times.
That said, if the team that gets chosen to develop the documentation
really wants to go the wiki route, I won't stop them. I'll just make
sure they look long and hard at their free time and how much of it
they are willing to dedicate to maintaining the wiki, above and
beyond writing and maintaining the documentation.
- Jamis
> --~--~---------~--~----~------------~-------~--~----~
> To unsubscribe from this group, send email to capistrano-
> unsub...@googlegroups.com
> For more options, visit this group at http://groups.google.com/
> group/capistrano
> -~----------~----~----~----~------~----~------~--~---
>