A Documentation-first Approach for APIs

Zachary Flower points out the importance of proper documention in his article “API Design: A Documentation-first Approach ” and even encourages a “documentation-first approach”.

He also cautions us against a “build-first” approach, utilizing existing architecture:

When designing an API, it is often desireable to take a “build first” approach, especially when utilizing the architecture of a pre-existing product. Unfortunately, this mindset doesn’t follow the standard usability practices that we follow when building apps with graphic interfaces. It is extremely important that we take a user-centric approach to API design, because we are developing a product to be consumed by other developers. If we can’t empathise with their needs and frustrations, then who can we empathise with? This user-centric focus is an important reason to start by writing your API documentation, rather than just designing it. When you create good documentation, good design follows, but the reverse isn’t necessarily true.

  • share  0 
  • share  0 
  • share  0 
  • info 

Ralf Westphal: About simplicity in coding

In Who do you want to KISS? – About simplicity in coding Ralf Westphal reflects on what simplicity means in programming.

He observes that simplicity is relative, esp. relative to the “scarcest resource”. For Ralf “in the long run the scarcest resource therefore is reading or modification time“. In TDD there is a step when you can create simplicity in respect to reading/modification time:

It means, you need to find time to optimize for reading/modification later. Interestingly TDD has this time built in. That’s what the refactoring phase is for. During refactoring you apply the KISS principle once more – now creating simplicity for reading/modification time. If thereby the simplicity for coding time is destroyed so be it.

And even then, simplicity regarding code reading and modification is in the eye of the beholder. Some programmers like high level abstractions like higher order functions while other like a more verbose but easier to follow procedural style. This is often related to the level of experience:

A simple solution for one person can be a complicated solution for another person. Sad, but true. The only way out of this is to keep all team members close together in their competencies (as long as there is a chance one member needs to deal with another’s simple solutions).

(This is a repost from my other blog)

Also on: