Suggest deprecation of "summary" tag in README / markdown. #11007
ghchris2021
started this conversation in
Ideas
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Suggest deprecation of "summary" tag in README / markdown.
Hello,
I appereciate all the great work from this project / organization and I use / refer to it frequently.
This is just a simple idea of what is really a possible change to the guidelines / practices of making the markdown "README" and other documents.
As an example on the main README.md there is this section which put the supported Models list in a summary tag:
llama.cpp/README.md
Line 41 in a813bad
When rendered to the github main page it just shows the little triangle mark and the word "Models" and nothing else.
In one browser anyway (Firefox) one has various means to search a document page's content such as a text search box, "find" command, the ability to start typing and default to a search action for the text, etc.
And one has of course the usual scroll wheel / scroll bar / arrow key / page-up+down navigation options to read the page content.
In my experience NONE of those "top level" ways to navigate or explore a page's content in that browser reveals that there is any of the 'folded' excluded content at all.
So if someone had a use case to see if say some model called 'granite' by keyword was supported one might well just start a find / search on the main page or appropriate README www view and see if what one searches for appears. It will not, by default, appear visually or in any search.
Instead the UX is degraded by 'summary' content because now instead of efficiently being able to use one's very fast UI means of search / find / scroll wheel / page navigation etc. keys to look for content one instead has to slowly scrutinize the whole page of content looking for
"buried easter egg" sections where one can click on a widget on a page one has ALREADY LOADED just to reveal otherwise invisible content (which in such cases as these are LARGE IMPORTANT sections of content).
And there are SEVERAL such hidden sections in the main README.md alone -- maybe 21 currently?
IDK how that even interacts with accessibility / screen reader features but I would not bet that 'by default' such content is easily discoverable / navigable that way.
Anyway I have a hard time conceiving of a more user experience hostile anti-pattern than having
a document loaded but then having to scan interactively for yet more places inside the loaded document where you have to discover magic spots to click to actually reveal the content that is supposed to be IN THAT DOCUMENT / page.
If something was so tangential / subordinate that it deserves another hyperlinked document / page, ok, then put it there and people could bookmark that page / file to quick-reference many things that are well covered there.
Putting things in "summary" defeats discoverability, searchability, readability, navigation, bookmarkability. And what's the benefit of it? To "TLDR" hide things that are actually important enough they're appropriate to include but somehow make them invsible by default?
One doesn't even do that with the TOC / appendix / bibliography / footnotes in normal documents. Sure maybe put some things in a different chapter, section, page, but adding a myriad of
other ways to hide things that should be "there by default" isn't good (IMO) UX.
And even when you (firefox as an example) go to PRINT the page (github web view) those things are STILL collapsed and the resulting PDF / printout does not contain any of that detail unless you
first go find all the expandable sections and one by one expand them.
Now if there was some kind of browser standard preference one could set in one's browser accessibility / preferences section like "expand everything by default", "collapse everything by default", "use the page's suggested default collapse/expand setting per instance", ok, I'd just set my browser to expand everything all the time and get on with 'search', 'scroll' navigation.
But AFAIK that doesn't exist and IDK if at the HTML/W3C/CSS/whatever levels there's any
guidance or specific option about controlling the expansion of such annoying little interactive page content pockets.
Some sites (web pages) are even worse and have a bunch of expandable sections in like a FAQ "page" but they're all contracted by default and expanding them is MUTUALLY EXCLUSIVE so it's literally impossible to see the entire "page" on screen or in a print out at once. I only mention this since I think this anti-pattern of unnecessary use of "hidden sections" is kind of like a "fad" that is more like a cancer on the web and it's arguably best to really consciously avoid the temptation to do this for the sake of following a user hostile fad anyway.
Even if I was on a phone browser with a tiny screen I'd still (personally) prefer by 1E9 factor just letting my finger scroll rapidly through the content or maybe search than go looking for places I have to click something just to see essential content I came looking for.
"Click here for the next 5 results..."
Anyway I'm suggesting (politely) to reconsider the UX of the practice for the above rationale
in documents / pages in general. Obviously there IS a work-around and it's "obvious" how to use the page "as intended". But it seems diametrically opposed to all "normal" UI practices of pagination / search / scroll / navigation we've established for decades.
Beta Was this translation helpful? Give feedback.
All reactions