On Mon, May 23, 2022 at 2:00 PM Rohit Goswami <rgoswami@quansight.com> wrote:

The contents are nonresponsive. No tool can fix a native responsiveness issues.  I am familiar with those tools. The questions is why work so hard when you have the HTML already?

I'm afraid I don't understand this argument. It is true that PDFs are not responsive without software assistance, but HTML documents when printed (e.g. CTRL+P) do not have any way of generating the Appendix / outlinks to related sections etc. Yet we still have HTML documentation. IMO this simply means they are not mutually exclusive.

The argument is about why one should use PDF on a mobile device. I am not even going to bother with the argument. The world moved on. See any app on your device. No one renders PDF. Because this is not what it is designed for. But everybody sends you a custom PDF for archival purposes. You might think they are all wrong but that's your opinion.

About this, the full page layout on the HTML pages has exactly the same amount of whitespace. It can be argued that for a full width layout there is exactly the same whitespace and indentation.

Additionally, even trying to print out say, np.einsum will first have 3 pages of the sidebar when using a naive CTRL+P approach.

The argument that the typography is poor goes beyond the documentation format.

In fact, even the "responsiveness" is rather overrated at the moment. With a mobile device again the first few screenfulls are simply the sidebar with routines and other things. After which there's still whitespace, and things are still just as indented as in the PDF. Only now I also don't have a global TOC which is easy to see.

It is not overrated. You are basically saying UX people are just doing bloated fancy work. This is not how things are designed. I am not recommending Ctrl+P on the HTML document. We are saying use the HTML files offline. This is again not an issue to argue about. The pages are following a Markdown format. If you want to have this subpar document you can generate it yourself. Having a burden on the CI system because maybe someone uses it is not sufficient reason to keep it.  Or at least that's my motivation.

The assertion that there is parity between serving ~2000 pages of documentation as HTML and ZIP files as opposed to a PDF seems to be flawed from the get go.

Again, you are comparing doc formats. The argument is to not to distribute PDFs. If you like that document regardless of its current state then fine do it. But as I mentioned, current state of affairs in the documentation world is not even bothering with PDF. When do you get PDFs? Exactly in technical manuals which are custom designed and provided with the products for archiving specific to that product. A documentation that invalidates its version every 6 months is again not a valid argument. PDF is a document format. And you have to generate it properly. Currently it is a very bad copy of the HTML version with no attention to the medium with which the information is presented. And the burden is on you to provide significant demand for it, the traffic to the site shows how much HTML is used.

I should add that NumPy does indeed have a dedicated docs team and consolidated effort. As mentioned earlier we meet regularly about these issues and it would be nice if the meetings are not unequivocally sidestepped by the mailing list. We also apply for funding (GSoD / NumFocus SDG) for our docs.

I understand there are frustrations with the PDF, but I am still not convinced at this point that the HTML versions are even at par with the PDF experience.

You are assuming that everyone is sharing your experience of PDF. I am also not convinced that abusing PDF format warrants its use in documentation. As I mentioned, the burden is you to prove its worth.  That's why we are proposing to remove it. Otherwise it wouldn't be discussed here and removed in SciPy.

It is nice that I have the time and ability to generate my documentation locally for my niche needs should I so wish it. It is less nice that we assume that it must be niche and everyone would have the same energy because HTML is theoretically more responsive, even though our docs are not.

That's what we started with, it is a long and annoying nontrivial process with diminishing outcome. We shouldn't spend this energy on a document that is not requested in general. If there is a demand for it we don't see it anywhere. Glad that we are aggressively agreeing.

Also HTML responsiveness need no proof. Just look at the page source on your browser and change the size of your window. The docs are responsive though not perfect (it collapses to the wrong frame in the smallest size for example but fixable) but definitely much more readable. PDFs are substantially more powerful than HTML but you need to exploit that by custom documentation. Not with auto-generated signatures. Technical writers, UX and documentation teams are doing extremely important job and making a static screenshot on a PDF is definitely not a viable replacement for that work. Or you might be missing out what the contemporary options are if you think it is.