My team does a lot of internal tooling and infrastructure work - you can think of us as a small scale version of the teams Facebook, Etsy, Netflix, etc. who build all the infrastructure for scaling their services up to thousands/tens of thousands of servers and supporting millions of users.

Lately, we've been running full steam ahead improving much of the tools we use internally, like tools for automatically creating new servers, setting up new application instances, etc. An end result of this has been decreased developer frustration, but increased 'ignorance' by most of the developer team about how to use our tools correctly and effectively. More often than not, my team will be asked by other teams to help them use the tools.

Solutions we've thought up or things already in place:

All our code is relatively simple and self-explanatory, with good comments where necessary, so developers could read the scripts.

Counterargument: You can guess this isn't a particularly good idea, having people read our tools' code to figure out how to use it.

All our code is committed to Subversion with very detailed commit messages about changes, developers could read the commit emails.

Counterargument: Expect the developers to read all our commits? Ludicrous.

Wiki - we have an internal company wiki, that we try to maintain with up to date information, but as we are moving so fast, the wiki has to keep pace as well.

Counterargument: As mentioned, we move fast in my team, as more improvements on our tools are added daily. Again still relies on people to read something that might change constantly.

Email the team? We could email the team when we have a glut of improvements to communicate.

So as you can all see, we are trying to find new ideas, and explore options we haven't thought of yet.

Anyone else ever been in a similar situation and have some guidance?

closed as too broad by gnat, user40980, Bart van Ingen Schenau, GlenH7, david.pfx Aug 20 '14 at 12:00

Please edit the question to limit it to a specific problem with enough detail to identify an adequate answer. Avoid asking multiple distinct questions at once. See the How to Ask page for help clarifying this question. If this question can be reworded to fit the rules in the help center, please edit the question.


Two angles here.

First, you've got to sell it to them. You can tell them about it all day, but fundamentally you need to make them feel that changing their ways and embracing new tools is going to make their lives better or easier. The end users need to see the benefits of it or they will never use it.

Second trick is what I call the "Cortez Approach". You might have heard the name -- he was the guy who, amongst other things, conquored the whole aztec empire with a few dozen starving Spaniards. And to make sure these Spaniards were motived, he made sure his first official act in the new world was to burn his own ships. He provided his end users no option but forward.

  • Thanks for the answer, I like the perspective. Of course, we aren't at the point where we can Cortez it, as it were, but we can definitely do painless demonstrations and developer talks about the dark corners of our art and see what we can do to help them adopt the usage. – wkl Mar 5 '11 at 0:16

I would say whenever you do a release update the release notes. Just like any software product. Have a brown bag to demonstrate new features so that everyone can see what's new and ask questions (if possible record and put it on your support site).

Wiki is great as well. Make sure that it stays updated though.

  • Thanks for perspective. I think release notes and wiki are a little more passive in getting the other developers to really buy into and adopt the usage of our new tools, so I think I'll talk to my immediate team and see if we can do a talk (with free food!) about using our tools. I like both yours and Wyatt's responses, but I'll accept Wyatt's since his score is lower. :) – wkl Mar 5 '11 at 0:17

Not the answer you're looking for? Browse other questions tagged or ask your own question.