The maze book for programmers!
mazesforprogrammers.com

Algorithms, circle mazes, hex grids, masking, weaving, braiding, 3D and 4D grids, spheres, and more!

DRM-Free Ebook

The Buckblog

assorted ramblings by Jamis Buck

Call for help: Capistrano documentation

14 November 2007 — 2-minute read

Capistrano’s documentation is, to put it mildly, lacking.

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 (jamis at jamisbuck dot org). We’ll see how many volunteer, and I’ll pick the “winner”. :)

If worse comes to worst, though, and no one volunteers, I’m still determined to work out some skeletal documentation as soon as I finish updating Net::SSH and friends. I have no ETA on that at this point, though. :(

Reader Comments

Excellent idea, it has been sorely needed for a while and almost all tutorials/examples/docs are out of date.

Great idea. Capistrano is a great tool but 2.0 does have absolutely no documentation.

I’m myself too swamped currently to be able to take on a leading role in this, but if someone does create a structure of “what chunks need to be documented” I’d be happy to contribute!

If someone browses this thread looking for volunteers, I can be reached at daniel dot cap at tenner dot_ org.

Daniel

Jamis, Can you point to another project with documentation that fits your vision or at least comes close to what you envision? Thanks, Ken

Yeah, this is pretty much the reason we ended up switching to Vlad. About the same amount of documentation, but about 1/10th as much stuff to document.

What ever happened to that rails deployment book?

Flashback: http://weblog.jamisbuck.org/2004/3/11/bitten-by-opensource

Ironic :)

Contrubuting to open source works great for both contributor and user community—contributor gets a bit of attention and experience at least.

Writing documentation for open source can’t be a real experience and it won’t let you show off.

There must be a fundraiser for that.

@Garry, that was a low blow, slinging my own words back at me. :) But valid.

@Yaroslav, money only takes you so far. When the limiting factor is time, no amount of money is going to solve the problem. I’m hoping that by delegating the documentation effort to the community, the time constraint will go away and things will start happening.

I’m pessimistic about this, though I wish you luck. One problem is that, while there’s glory in code, there’s no glory in documentation. At events like RailsConf, people see you and say “Holy crap, there’s Jamis Buck, the guy who wrote Capistrano!” (and then subscribe to your blog). Your best bet is to find a way to reward documenters with some reflected glory, so that people might also say “Holy crap, there’s Joe Blow, the guy who wrote that awesome Capistrano documentation!” (and then subscribe to his blog). Until that happens, expect most open-source documentation to continue to suck.

I’ll budget some time to help the cause. Lord knows you’ve made my life easier with Capistrano. :)

@Michael, I suppose I have a more optimistic outlook on things. I’ll hope for the best. And of course I’ll do everything I can to reflect “glory” (if you can call it that—it feels more like an immense pressure to perform) to everyone who contributes.

I’d be more then happy to assist in any way. If for nothing else then it would be a great experience documenting Capistrano.

I would like to volunteer to coordinate the documentation effort. When I did my rails applications I used Rake, but I can figure out Capistrano and have written documentation before (although mostly code). Email me if the task has not been started by someone else.

-mat

How about

1.) Cheat sheet 2.) List of variables and options 3.) Tutorials 4.) How to troubleshoot common problems

That is what would help in order of importance from a user of your wonderful set of tools.

If you ever need newbie questions for a FAQ, I’m in! By the way, why doesn’t df | grep 8-9% work in cap shell?

I’m up for helping out. Fairly swamped, but it’s a good cause.

I haven’t used cap for a while but got stuck in a while ago customizing it for my needs, what with my company’s need for hard-linking and no svn on the server – twas a fun time.

Let me know Jamis.

Andy

Hear, hear!

Especially some good API documentation! I was trying to create a new scm for Capistrano but is was more guessing than programming due to the lack of good documentation.

soon as I finish updating Net::SSH and friends. I have no ETA on that at this point, though. :([/quote]

Any word on when this will be available?

Would it be worthwhile to open up for community involvement? Maybe a list of what’s left to do?

@Mark, if you’re interested in taking a peek, I can post the repository URL’s again (they’ve been posted here before, but I can’t remember them off the top of my head). I’d welcome patches, but to be honest, about all that’s left is writing tests and documentation, and I’m slogging through that now. Maybe a release by the end of January?