http://blogs.msdn.com/stevencl/archive/2003/11/14/57065.aspxDescribes how to combine scenario based design, task analysis and the cognitive dimensions framework when designing an API.en-USCommunityServer 2.1 SP1 (Build: 61025.2)http://blogs.msdn.com/stevencl/archive/2003/11/14/57065.aspx#57066Sat, 15 Nov 2003 20:12:00 GMT91d46819-8472-40ad-a661-2c78acb4018c:57066Frank HilemanI have one quibble: the distinction between "goal" and "task" seems completely arbitrary. They are one and the same; the "goal" is a task, and a "task" is a sub-task. These can nest to any level. Once this distinction is removed, the difference between a "primitive" and any other component is hard to see. The term "primitive" might be better used to describe the lowest level operation in the API. These are great ideas! Years ago I worked on a development team for a public, widely used API in C. We decided that all new public additions to the API had to have preliminary documentation written before the API itself was developed. The documentation had to include samples of the most common uses. We found that the process of writing the documentation and samples often caused radical changes to the design of the API. Since these changes occurred before a line of code was written, they happened at the cheapest point in the development process. The rising popularity of "Test before development" is achieving some similar benefits, by writing tests using the API before the API is developed. The "doc before development" order arose because the more traditional "develop then document" order often caused severe redevelopment costs and unpredictable deadlines. Developers think they know precisely the requirements for an enhancement, when in fact, the requirements are not really known in detail until the end user documentation is created. Giving developers a role in documentation also forced them to see how difficult it might be to explain the "monster" they were creating. They could see the "monster" for what it really was, from the user's perspective.http://blogs.msdn.com/stevencl/archive/2003/11/14/57065.aspx#57067Mon, 17 Nov 2003 07:48:00 GMT91d46819-8472-40ad-a661-2c78acb4018c:57067Steven ClarkeYour point about the definition of a task is well taken Frank. As you may know, it's a well debated topic amongst usability folks also. However, my aim in using the term in this context was to focus on the user's perspective when thinking about the design of an API. A user has a particular goal or state that they want to achieve and a set of tasks or operations that they think they need to perform to achieve that state. The difference is in describing a goal as the final state that a user wants to achieve and tasks as the way that they expect to achieve that state (which as you say, will involve reaching some intermediate state). When thought of in this way, it's harder to describe a set of tasks as a set of goals in and of themselves since it's less likely that a user would describe a task as a final state that they would want to achieve. For example, it's more likely that a user will open a file in order to do something with the contents of that file. And many users would expect that in order to read from a file, it needs to be opened first. It then follows that the abstraction level of an API can be measured with respect to the user, rather than the API itself. One user's aggregate component could be another user's primitive - it all depends on how the user would describe the tasks that they think they need to perform to achieve a particular goal. Writing the documentation first is a great way to see the API from the user's perspective as you describe. What we are trying to do with the framework is to measure what we are seeing and to use these measurements to direct API teams to design something that will work well for our users.http://blogs.msdn.com/stevencl/archive/2003/11/14/57065.aspx#66716Tue, 03 Feb 2004 20:24:00 GMT91d46819-8472-40ad-a661-2c78acb4018c:66716stevencl's WebLoghttp://blogs.msdn.com/stevencl/archive/2003/11/14/57065.aspx#70898Wed, 11 Feb 2004 01:30:00 GMT91d46819-8472-40ad-a661-2c78acb4018c:70898stevencl's WebLoghttp://blogs.msdn.com/stevencl/archive/2003/11/14/57065.aspx#87680Thu, 11 Mar 2004 06:10:00 GMT91d46819-8472-40ad-a661-2c78acb4018c:87680VS DATA Team's WebLog