1) Have the internal team use the same public API as much as possible. I believe Steve Yegge (of Google and Yahoo) wrote a long article about this concept. He

1) Have the internal team use the same public API as much as possible. I believe Steve Yegge (of Google and Yahoo) wrote a long article about this concept. Here's a link[1] but I can't remember if it's the definitive one I read before. By forcing your internal developers to use the same API, you see the frustrations of any incoherent designs that outsiders would see. Also, bug fixes fix the defects for private & public users. 2) Design the API to encourage clients to stumble into the "pit of success." I believe Microsoft's .NET team originated this phrase.[2] This means sensible defaults for the the most common tasks. It leads to related maxims such as "make easy tasks easy and hard tasks possible." 3) Additional documentation that's organized thematically around "tasks", "workflow", "usage scenarios", and "concepts". It's not enough just to have a dump of functions listed in alphabetical order presented as a "reference guide". The reference guides are important but people unfamiliar with the new API need some handholding and reference guides don't do that. The task-oriented documentation would be things like "Getting Started" or "working demos". [1]http://apievangelist.com/2012/01/12/the-secret-to-amazons-success-internal-apis/ http://apievangelist.com/2012/01/12/the-secret-to-amazons-su... [2]http://blogs.msdn.com/b/brada/archive/2003/10/02/50420.aspx http://blogs.msdn.com/b/brada/archive/2003/10/02/50420.aspx