Mixed Metaphors

I've been meaning to talk about some of the design decisions regarding OneNote DataImport for a while now...

If OneNote was a house, you could think of our SP1 as the ultimate in remodelling.  Trading Spaces on crack: new hardwood floors, reupholstered furniture, a bit of paint, and let's not forget the nice new kitchet cabinets.  It's pretty fancy.  Yet at the same time, it's still the same basic foundation and house.  Sure, we may have added a couple new windows, an extra bedroom and a patio, but we didn't knock down any load bearing structures or add a new basement.  

(And it turns out that you actually need building permits for serious construction work!  Think about all the cases where people want to upgrade yet prefer to minimize risk or UI changes; particularly in the enterprise where user training can be prohibitively expensive.  As a result, all of our new features have to be disableable upon demand.  If you set the registry key HKLM\Software\Microsoft\Office\11.0\OneNote\EnableSP1FixesOnly to the DWORD value of 1, walls slide out of hidden recesses, the cabinets flip upside down, and Dexter's secret laboratory is safely disguised.  Explosion?  What explosion?  I didn't hear anything.)

Partially, constraining your development to the periphery helps keeps development costs low and mitigates scheduling risk,  but it's also important to remember that software also requires a significant amount of testing and stabilization work.  (In general, most software schedules throughout the industry allocate roughly 1/3rd of their scheduled time to design, 1/3rd to development, and 1/3rd to testing.)  Every code change has the risk of negatively interacting with other parts of the system, and the entropy will only increase with time.  

Testing extensibility is particularly hard.  Unlike most UI features, APIs are generally open ended systems, that can take an infinite number of inputs.  This is partially mitigated by reusing existing codepaths which have already been tested.  For example, importing html uses the same HtmlImport code as copy/paste, etc.

Speaking of costs, let's not forget startup.  As the first release to offer any extensibility, you have to account for research, minor architecture work in the codebase, etc.  It might not sound significant, but it adds up when you're working within a shortened development timeline.

Design issues such as security and maintainability are also important, and you really do have to get them right the first time. APIs have a habit of outliving most peoples expectations.  They're hard to kill.  So it's important to be certain that what you ship will last a long time, and won't bite you in the long run.  The software landscape is littered with examples of projects that chose to implement their automation interfaces directly on top of their code internals; which certainly afforded clients with the utmost flexibility and seemed like a good idea at the time...   Lastly, your APIs have to be secure from inception.

All of these constraints dictate that you can't go hog-wild.  You have to choose your scenarios carefully, and refrain from excessive generalization.  You need to be spend-thrifty, reusing what you can whenever possible.  And you have to be a bit cautious, too.

The rest is history.