Open Stack

On 2016-09-06 17:42:03 +0200 (+0200), Ihar Hrachyshka wrote:
[...]
> There are two related but separate questions here:
> - is there time when we can drop API from api-ref when it’s removed in code?
> - if so, when is it: right when the API is dropped, or when all branches
> supporting it are gone? or should we document the non-existing API
> indefinitely?

Agreed, this is where opinions are going to start coming into play
because there's a trade-off in trying to maintain documentation for
dead-end features indefinitely. Ideally you'd keep it documented
until such time as you feel there's not enough people likely to
still be relying on the documentation for that feature in the wild
(once major service providers and distributions are no longer
supporting it). That could be a long time though, and there are no
easy answers... it's a matter of your documentation authors weighing
cost and benefit to pick an appropriate time for the project and its
downstream consumers.

Though hopefully once you do drop it, there's not much burden to
indefinitely maintaining a note in the documentation acknowledging
that it used to exist (perhaps mentioning the location in revision
control from where the old documentation source could be exhumed)?
-- 
Jeremy Stanley