Mention more prominently that section ordering matters

[stefanv]

Mention this in HOWTO_DOCUMENT.txt

[tacaswell]

Or explicitly drop the order as a requirement ;)

[rgommers]

Having a standard ordering of sections in docstrings within and between projects is a good thing - consistency matters. Why would we want to drop this requirement?

[tacaswell]

It seems a bit weird to have a required order on optional sections.

I agree that for some sections the order make lots of sense (should not put Parameters last and References first), but shuffling sections 7-11 does not seem like a huge issue to me. There is value in letting people pick an ordering there that makes the most sense on a function-by-function basis.

To be clear, I will be perfectly happy with the outcome of 'It is an intentional choice to have a fixed order' from this discussion (so as to not waste even more of everyone's time).

[stefanv]

I don't feel strongly about the optional section ordering.  I'd be okay with that remaining flexible.

[stefanv]

I'm changing my opinion on this one after other discussion.

See #78

[larsoner]

My vote would be to optionally, on-by-default warn if optional sections are not ordered with the "standard" ordering.

[jnothman]

In order to open this to another contributor, I'm making a new issue instead.