I just finished reading chapter 2 of Framework Design Guidelines by Krzysztof Cwalina and Brad Adams that discusses Framework Design Fundamentals.  Even though the chapter is only 26 pages long, it is filled with a lot of good advice on how you tackle the API of a framework.

Focus on Usage Scenarios ( Scenario-Driven Design )

Focus on the 5 to 10 most common usage scenarios of the framework.  First write the code you would want your user to write, and from there start looking at the types, hierarchy, and abstractions to support the API.  This has somewhat of a TDD feel to it.

Do not start building your framework and API by looking at types, object hierarchy, and abstractions.  Althought important concepts, OOP is about building a maintainable and extensible framework, not about creating an API that is intuitive to the end user and has a low barrier to entry.

Keep the Simple Things Simple and the Complicated Things Possible

Here they stress the 80/20 rule in that in any situation 20% will be important and 80% will be trivial.  When building the API for your framework, focus on that 20% that is important and keep things simple.

Most people learn not by reading documentation, but by tinkering with the API.  Developers need to be able to use the API for those 20% more important reasons by creating as few objects and setting as few properties as possible.

Progressive Frameworks

Avoid creating separate frameworks for the simple cases and advanced cases, because typically there is no transfer of knowledge when you move from the simple cases to the advanced cases.  One usually incurs another learning curve when changing frameworks.

Instead, create a progressive framework that keeps the simple things intuitive, but offers additional advanced classes/features ( usually placed in another namespace ) for advanced scenarios.

Layered API Architecture

High level APIs offer productivity and simplicity while low-level APIs offer expressiveness and power.  Because developer preferences and needs will usually dictate one or the other, it is ideal to separate these APIs in different layers via namespaces for ease of use, but in such a way that if the developer needs to switch to another API level a complete rewrite is not necessary.

A lot more ideas and principles presented in the chapter.  This is proving to be an excellent book and I am only at page 32 :)

Drinking:  Gyokuro Green Tea