Talk:DocumentDeclarativeAPI

From APIDesign

Too many developers are focused on the mechanics of how a task will be performed and the steps required to perform them. Typical documentation of software explains what command line switches are available, but not why you might want to use them. I have been frustrated by this for years. I always skip to the "Examples" section of any doc, as I usually can infer use cases from the examples far better than from studying method signatures in the abstract. A classic example would be the Java API docs. Why would I want to use a LinkedHashMap? Maybe I slept through that lecture in CS class. It would be neat to make a pivoted set of docs for the JDK in terms of patterns, like LRU Cache => LinkedHashMap. The only way I've learned Maven is to study other people's POMs, guess-and-check, and then discuss.

-- Basscakes 15:55, Sep 15, 2009