Your documentation seems limited to basic functions, with nothing explaining really what this does, or why I would need it. I've just spent like 20 minutes looking all over it and I have no idea what to do with it.
Thanks for your feedback, this kind in particular is very helpful and valuable.
We have a video explanation and walk-through of shipbuilder in the works which should help communicate more clearly about what ShipBuilder is and what it can do for you.
I have a few additional questions if you wouldn't mind helping me improve this aspect of Shipbuilder:
1. Have you used Heroku before?
2. Are you confused about the purpose of ShipBuilder?
(i.e. "what does Shipbuilder do?")
3. Are you confused about how to setup the ShipBuilder
4. Are you confused about how the client works?
Finally, please feel free to contact me personally; I'd love the opportunity to answer questions or help you (or anyone) get started with ShipBuilder.
contact info: #shipbuilder on irc.freenode.net or jay [at) jaytaylor do.t com
Look at how easy heroku makes your first few steps. I'd advise doing something similar but with, for example, instructions for setting up a quick shipbuilder server on amazon ec2 or the like. Bonus: it will show you where the pain points are for shipbuilder at the moment, because you'll have to write too many small gotchas&workarounds into the tutorial!
I think the main question that would help me would be "Why do I need Shipbuilder?" with different examples of when I would need it, how it compares to other tools, what it was designed to accomplish, all the system and network dependencies, and a breakdown of each individual component and how it works with other components. Mainly I want to be able to have an image in my head of how it fits into my network/system, what it might replace, or how I can take advantage of it.
How does ShipBuilder compare to other open-source PaaSes like http://www.cloudfoundry.com ? CloudFoundry's pretty far from production-ready at this point, but it does have the huge advantage of supporting existing Heroku buildpacks.