I was going to reply on Twitter with a cryptic response and a bunch of abbreviations, figured I would expand. Maybe the gist comments would faciliate people being more expansive. To me, Twitter is good for information sharing, bad at following conversations. I always miss a post or two.
I have a blog post half written (don't we all...) about doing things that are painful more often and trying to automate them, so this struck a chord. Also, at $JOB, the simpler the process can be for getting someone onboarded and for me to get new dependencies as they are introduced to the project, the better. So this is something I have been thinking about.
I liked Matt's original post and followups. Why aren't more internal / private projects as easy to get started with as popular open source projects? I looked at the Stringer docs today actually, and you don't even need to install anything, it is a click-one-button-and-some-change operation to get it running.
It is frustrating to me to come onto a project that has three wikis and try to get the project running. You have to work with five other people to get the app running. When you do, you are not sure if it is set up properly because it looks funny because you don't have the seed data. Then when you do get it totally running, half of the tests are broken. (Matt didn't say this explicitly, this is just my experience.)
I agree that each developer who comes on should try to move the project documentation / tooling forward. One of the best values of having someone new come onto the project is they see it with fresh eyes. "Why isn't this working?" "Oh, you need to froble the xnarfulator. We changed that a couple of months back and didn't update the docs. It's in Slack somewhere..."
I do not think that developers who chafe at needing to spelunk the codebase and rely on old documentation to get the project running and get up to speed are not good developers or are otherwise inadequate. I think it is more of a process failure on the part of the current team.
Code as documentation is huge. I could write (and have written!) a 200 line Markdown file that you need to read through and copy/paste to get your environment set up:
- getting imagemagick, redis, postgres, xml2pdf, and xnarfulator (possibly the best made-up name of all time)
- getting your database set up
- copy this file here and change the settings
- running database migrations
- setting up your deployment tooling
- and more...
And this needs to be both correct and up-to-date at all times.
Or, we have a script that is committed to source control that everyone regularly runs. When that breaks, we fix it, and everyone is better off for it. The final documentation could be as simple as:
# README.markdown
Clone this project by running git clone https://github.com/panozzaj/my-smooth-project.
Run ./setup in the newly created directory.
Now you can run the server by saying `rails s`. Hurray!
The explanation of what you just did and how to administer it is at `doc/setup.markdown`
with the rest of the docs in that folder.
I agree that it is important to know what is going on, but this is repetitive and prone to error. Why not let the computer take care of that? If it is really complex, I don't want to have to know all of the detailed setup right when starting. It seems to me like the more complicated the system, the more tooling and automation needed in place around it to not mess things up. I personally would rather have a well-documented project with good tooling that was far more complex, than an only moderately complex project with a half-baked wiki.
There's the lottery factor to consider. Your two most senior developers (or even the whole development team, if the team is small enough) wins the lottery or changes companies or changes projects or is generally unavailable. By documenting the system and especially building tooling (simple scripts, etc.), this knowledge is not lost.
I'd also like a sandbox that replicates/simulates the production environment locally so I can test out changes. Seems far-fetched? http://docs.docker.com/compose/
IMO the ideal state for a project of > ~20 developers would be to hand someone a new laptop, and on the same day that developer can deploy a trivial change to the live production system. It should be so easy that dogs can deploy code (slide 17). This is the state of the art. This kind of investment makes most sense when you have a large team.
Well... I just got really excited there. I think the biggest value for me is asking, what can we do today to get us closer to that goal? Would we be better served adding three developers today, or having the existing developers each spend two hours on tooling and starting the three developers a week from now?
May turn this into a blog post at some point since it is so long. Thanks for reading!
Re: Code as Documentation
Vagrant has been great for this at work. All database setup (schema, user accounts, test data, triggers, migrations, etc) are all in a Git repository with a Vagrantfile and a provisioning script, so any developer can bring up a local copy of the current database (or old versions with Git history).
Most of the software projects are Java, so we've informally standardized on Maven, so dependencies are explicit, and anyone can make a build with maven install.
There will always be a few things that slip through the cracks, but these two things have made project handoffs between developers almost seamless. Definitely lowers new project frustration factor dramatically.
When do we add to tooling?
I did a lot of work on tooling when I started my current job. It solidified my understanding of a lot of projects. And as a new hire, I had an empty plate, with no responsibilities hanging over my head, so I wasn't stealing time from other projects to work on it.