Moves package information to the end of the file

[ffunenga]

• moves information about the Python package to the EOF
• simplifies initial headers

[The-Compiler]

Not sure about this, I'd prefer having that (quite useful, IMHO) information at the top, and it doesn't take up much space there.

[ffunenga]

Got it. I won't be contributing further to this project.

[hpk42]

filipe, not sure i understand. You don't want to be contributing further because florian (and me, actually) think having short package meta info at the beginning makes some sense? Or because of some other reason? He even marked it as "IMHO" which means "in my humble opinion", he didn't close the PR or anything but left room for further comments and discussion. Or is merging the only action which would satisfy you because you think it's not a big deal and warrants no discussion?

[ffunenga]

@hpk42 and @The-Compiler I should have been more explicit about why I won't be contributing further to this project. This is what just happened from my perspective:

I looked at the documentation and I saw a lot (!) of things that could be fixed (I am only talking about the documentation, not the Python package per se). I grabbed the first most basic and obvious thing that came into my mind if I were to fix anything, and I made a pull request here to see what kind of environment I would be getting into.

The first write-access contributor opinion I get (and now yours, which makes it even more clear to me), shows me that you are empirically making decisions about the documentation, having in mind, most of all, what a contributor would prefer. Hint: The contributor is not the reader you should be thinking about when drafting the documentation.

My reasoning was this: If we haven't even started with the work that the docs require and I am already getting an empirically-based barrier about something so obvious and simple, then I don't see much use of my technical drafting skills here. I imagine I would only gain frustration from trying to fix the documentation of this project. So, I moved on, without bothering anyone further with pull requests.

Now, in your comment you reveal that the actual reason for maintaining package meta info at the beginning is because it

makes some sense

I profoundly disagree with this type of thinking. What does your "some" actually mean? What are you actually saying? What is the scenario in which you think it makes "some" sense? Can you point out a practical example where it makes "some" sense? And, by the way, why is "some" sense enough? Why isn't the threshold defined at total sense in all possible cases?

[The-Compiler]

Thanks for the follow up. Let me try and adress those points - and let me make this clear again, it wasn't my goal to discourage you from contributing to the docs (or to anything else, for that matter!).

I looked at the documentation and I saw a lot (!) of things that could be fixed (I am only talking about the documentation, not the Python package per se).

I agree, and making the docs more clear is very much needed and appreciated. For example, see #1112 and other issues with the docs tag to get an idea of what's missing from our perspective - and please contribute yours!

The first write-access contributor opinion I get (and now yours, which makes it even more clear to me), shows me that you are empirically making decisions about the documentation

No, those are opinions, not decisions. I haven't told you I'm firmly against that (or rejected your PR), I merely stated my opinion on this matter and hoped for other opinions.

having in mind, most of all, what a contributor would prefer. Hint: The contributor is not the reader you should be thinking about when drafting the documentation.

What makes you think so? As a contributor, I'm likely to know how the package is named on PyPI, what Python versions it works on, and what dependencies it has.

As an user of any project, the first thing I want to know is what its name on PyPI is, and if it works with Python 3.4/3.5 (because that's what I use for my own projects). Sometimes that's painful to find, and I'd still argue this information doesn't belong at the bottom of the docs.

As for the PDF docs, I don't see how a contributor would be interested in those more than an user either.

My reasoning was this: If we haven't even started with the work that the docs require and I am already getting an empirically-based barrier about something so obvious and simple, then I don't see much use of my technical drafting skills here. I imagine I would only gain frustration from trying to fix the documentation of this project. So, I moved on, without bothering anyone further with pull requests.

You're not bothering anyone - and as said, we'd very much appreciate some help with the docs, I agree they're unstructured and confusing in some places.

Now, in your comment you reveal that the actual reason for maintaining package meta info at the beginning is because it

makes some sense

I profoundly disagree with this type of thinking. What does your "some" actually mean? What are you actually saying? What is the scenario in which you think it makes "some" sense? Can you point out a practical example where it makes "some" sense? And, by the way, why is "some" sense enough? Why isn't the threshold defined at total sense in all possible cases?

Okay, so having that information at the bottom makes total sense in all cases, but having it at the top doesn't? I disagree with that type of thinking. It's very much subjective, so let's see what people other than you and me think.

[ffunenga]

I can't waste my time here. Do whatever you want with your documentation. If you like how it looks, than good for you!