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: arch...@mail-archive.com