This goalpost is moving too much. I am not drawing parallels with SciPy to make a point on NumPy. I am using it to give another data point where we did exactly the same thing with zero backlash providing its usage frequency. You might think they are separate but the user base is surprisingly similar. I think you are underestimating SciPy about its complexity or affinity to NumPy.
I also made real life cases where keeping a running infra about TeX is a mess. And it's not a hypothetical, these cases are commercial cases where results are way more important than NumPy. Nobody except a measure of zero is using it. So again, another data point. Not doing any effect. Mobile experience is again a weak argument. If you have your mobile device use the online docs. I think I can see the number of people who would read NumPy documentation with offline mobile devices so that would not be a valid argument. I'd be happy to see the demand though. I cannot take it seriously that PDF reading on a mobile device would surpass HTML, even desktop apps are electron based HTML. You can argue our HTML experience would need work and that's a valid argument but worse than PDF is not going to fly. If you want to keep your stance you are welcome to do it. But run it with other people who do this for a living. I think I have made my case sufficiently times by now. You are arguing your point from your personal perspective. So I don't have to entertain it. If you think this technical manual is good then we have quite different opinions about quality of a technical document. But you still have the burden of proof to demonstrate the demand for it on the CI system which you have not provided yet. And that is the point here without putting any obstacle on users who prefer PDF manuals can still generate it. I'll leave the decision to others to not to generate more noise. On Mon, May 23, 2022 at 3:06 PM Rohit Goswami <rgosw...@quansight.com> wrote: > 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. > > Lets agree to not talk about the world here a bit, user profiles vary. I > have three browser apps true, but also a bunch of PDF readers. > > But in any case, lets talk about the UX a bit. > > We are assuming that instead of downloading one document and using that > when there is no internet: > > - Go to pg. 50 on numpy-ref.pdf > > We would instead be: > > - Explaining how to unzip things on a mobile (default file managers > are not guaranteed to come with zip support) > - Explaining how to use offline HTML (or even better, have them find > the file of interest and open that with the local path) > - Tell someone to either use the search or navigate the rather baroque > mobile interface to find something > > Because the average user in a low network area is clearly going to be > aware of all this. > > Mostly because we don't believe PDFs are viable. Also, the Reference > Manual is exactly what I'd expect from a technical manual. The argument is > on the other side, that trying to actually read or use the HTML document as > a replacement for the Reference Manual is rather unlikely. > > Again, the intents differ, perhaps for something like SciPy, a > user-focused library, a reference manual enumerating API design and > decisions doesn't make much sense. NumPy has a lot of design documentation > which is kanged from an actual book... > > Again, you are comparing doc formats. > > Nope, it is the information content and ease of access, see usage pattern > above for an offline developer. > > It is not overrated. You are basically saying UX people are just doing > bloated fancy work. This is not how things are designed. > > This is not what I meant at all, I have a deep love for frontend work, I > was merely pointing out that at this point in time I don't think our > "responsive" HTML is any better than our "broken" PDFs. I think we'd be > hard pressed to find anyone saying the current HTML documentation follows > best responsive practices (the sidebar should be minimized, I shouldn't > have to scroll for tens of seconds to get to text I was looking for, the > list goes on) > > That's why we are proposing to remove it. Otherwise it wouldn't be > discussed here and removed in SciPy. > > Removed in SciPy really needs to stop being part of this discussion. > Unless we want to merge the projects back together; we don't *have* to > evolve in lock-step. Hence the discussion. > > If there is a demand for it we don't see it anywhere. Glad that we are > aggressively agreeing. > > Why do we expect people to request a document we already provide? This is > the first time we have this on the mailing list, so we should simply defer > the discussion. We can add analytics to the /doc page and check back in a > few releases. IMO the argument about "load" is a bit fallacious, we don't > actually seem to be generating or serving PDFs per commit (but I might be > wrong). > > Also, definitely not agreeing at all yet :) > > 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. > > Here are some steps to reproduce the mobile experience. They rely on > either using an actual mobile device or "web inspector" or "developer > tools": > > - Switch to a standard format, and watch the sidebar take up most of > the real-estate > - Try using the zip as discussed above > > Additionally, I really don't intend to bash on the HTML, of course we > could add more breakpoints, and special casing until it looks / behaves > better. > > Until we do so, the removal of the PDFs seem awkward. > > As for CI load and metrics, we don't have hard numbers for a lot of these > things and it feels strange to discuss what we feel is "responsible use". > > --- Rohit > > P.S. By happy coincidence, I see we have an upcoming documentation meeting > in around 3 hours. As always, everyone is welcome to come discuss here: > https://hackmd.io/oB_boakvRqKR-_2jRV-Qjg > > On 23 May 2022, at 12:42, Ilhan Polat wrote: > > > > On Mon, May 23, 2022 at 2:00 PM Rohit Goswami <rgosw...@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. > > > _______________________________________________ > NumPy-Discussion mailing list -- numpy-discussion@python.org > To unsubscribe send an email to numpy-discussion-le...@python.org > https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ > > Member address: rgosw...@quansight.com > > _______________________________________________ > NumPy-Discussion mailing list -- numpy-discussion@python.org > To unsubscribe send an email to numpy-discussion-le...@python.org > https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ > Member address: ilhanpo...@gmail.com >
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-le...@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: arch...@mail-archive.com