openstack team mailing list archive

["Caitlin Bestler" <Caitlin.Bestler@xxxxxxxxxxx>]

Thierry wrote:

> And now, the architects vs. developers discussion :)

> I hear both sides of the argument, and I think both have very valid
points.

> However, so far we have been following the "architect" way (design
upfront and separately from code),
> and it's failing miserably.


That analysis omits a very important third party: users of the API.

One of the reasons for documenting an API separately from the source
code that implements it
is that it isolates the users from having to understand the
implementation.

The problem with auto-generating API documentation is that it seldom
fosters a proper respect
for the value of a stable, consistent API that might evolve to support
new features but keeps a
consistent approach.

The other shortcoming is that it tends to omit behavioral specification,
and instead focus on
Enumerating fields in requests.

The major advantage of generated API documentation is that it can be
edited with the same
tools as the source code is edited, and it makes a proper distinction
between the specification
of the API (something that should change very slowly) and tutorial
explanations of the API
(something where continual improvement should always be welcome).

While the build environment does not require it, "API specification
files" that were sufficiently
segregated from the general source files so as to encourage careful
consideration when extending
the API would provide the benefit of a single set of tools, and
hopefully not create an environment
for outside developers where the API is subject to frequent churn.