On Fri, Feb 19, 2016 at 10:02 AM, Tony R. <report@bugs.python.org> wrote:
> Holy crap!  You all used to use LaTeX?!  :D

Python's documentation has a long & colorful history.  :-)

> Well then, if this is the sort of place where the status quo is sacred, then
> there is nothing more to discuss.

Status quo is not sacred, but does have some value.  Changing how busy
people do things is non-trivial.

> But if anyone reading this is open to the idea, please re-read my previous
> comment in this thread.  The quoted LaTeX docs are clear, but I still
> believe my “all changes = (deprecated-removed changes) + (added
> changes) + (other changes)” interpretation makes more sense than the
> LaTeX definition.
>
> I also think it is more helpful to the *reader*--which, I respectfully suggest,
> should be the basis for any documentation’s guidelines--by marking up
> changes according to this grouping.

I think we all agree that the documentation is for the reader.

> It’s not my desire to be troublesome by making one more appeal.
> I simply want to point out that just because somebody wrote the
> LaTeX definitions a long time ago doesn’t mean that we cannot
> rewrite them.  They were written by somebody just like us, after all.

As the person who wrote them, I don't consider them sacred or
unchangeable.

Having some rational basis for whatever we use is good, and it should
be clearly documented clearly.

> If it’s not obvious by now, I feel strongly about good semantic markup.

We're on the same page here.

> The purpose of semantic markup is to describe what something *is*.
> I just think that changes form a hierarchy, with a generic “change” as
> something of the base class, and “deprecated”, “removed”, and “added”
> as specializations.

Again, agreed.  That doesn't imply that the specializations encompass
all changes, though.  For some, 'versionchanged' is reasonable.

Part of the problem is getting the granularity right.  The initial intent was
that 'version*' were annotations for the enclosing object (function, class,
method, etc.).  If we want to have something more granular (parameter
added / deprecated / whatever), we should have distinct markup for that.

That could look something like:

    .. parameteradded:: alternate 3.6
       Further explanation goes here.

It's helpful to think of these annotations as pronouns; the antecedent
needs to be clear before they can be interpreted correctly.  It sounds
like that needs to be clarified in the documentation, and possibly
provision added for a more fine-grained form of annotation.

  -Fred