Clojurians Log v2

Hiya @akshat.iitj! There is no support for this yet, but there is an old open https://github.com/cljdoc/cljdoc/issues/89. If we were to add this feature, at this point, since we've been sorting alphabetically for so long, we'd still default to that, but could allow to switch to sorting by line number through some ui control. Is that what you were hoping for?

Hey @lee Thanks for responding. I'm looking for 2 things, 1st is must have, 2nd is nice to have. 1. Sort functions by line number within a namespace 2. Define an ordering for namespaces in the side-column

> allow to switch to sorting by line number through some ui control This config should be baked into code & not in the hands of the users. Reason being, custom ordering helps authors provide a coherent story-line for their users.

@akshat.iitj thanks for taking the time to elaborate! Note: there are no "must haves" in open source simple_smile Cljdoc has been sorting vars alphabetically for some years now. We should take into account that some people might prefer that, regardless of a library author's preference. I think you are suggesting that sorting vars by line number is very important to some library authors and should be the configurable default for a library, perhaps in cljdoc.edn. Custom sorting of namespaces, to my knowledge, has not come up yet as a feature request. If enough folks really want this, we could maybe consider it, but let's focus on var/fn sorting for now.

> there are no "must haves" in open source Ofcourse. By must/nice haves I was communication my need/priority of requirements. Sorry for the incorrect wording > We should take into account that some people might prefer alphabetical sorting I see cljdoc as a wiki/presentation, (ofc the source code should also be presentable). In a presentation, I feel ordering should be left to presenter. > let's focus on var/fn sorting for now ✅ We have a difference of opinion on who does sorting? How do we go about resolving that?

The way I see it, users might become confused if one library has vars sorted one way and another library has vars sorted a different way. The inconsistency would confuse me, for example. A user might not also agree with the library author's sorting choice. Even if that library author has very strong opinions on the matter. 😉 > ofc the source code should also be presentable I'm not sure what you mean here. Are you suggesting cljdoc should also present the library's source code?

> users might become confused if one library has vars sorted one way and another library has vars sorted a different way Alrighty then. Sorting from UI based on user preference it is ✅ > ofc the source code should also be presentable Can be ignored. I was meaning to say a clean code file leads to a clean documentation

@lee how do we take this forward?

I've gone as far as updating the https://github.com/cljdoc/cljdoc/issues/89.

Would cljdoc need cookies consent to retain user preference globally?

If I remember correctly we are using local storage to remember recently visited libs. And... indexed db... to support client-side docset searching. So we'd probably use local storage or cookies.

I was never asked for a cookie consent, so asked if our design would change UX. Seems like it won't

Oh. Maybe that's an advantage of using local storage instead of cookies?

Also feel free to chime in on the issue if you have ideas or see any issues with my initial proposal.

We'll also have to figure out how to elegantly add the UI control to change this sort option.

Is there a UI-person in the maintainers of cljdoc we can ask?

I'm OK at this kind of stuff, but always appreciate the feedback/opinions of @corasaurus-hex. She just started a new job, so might not be available.

If there are any other UI-smart cljdoc developers lurking, please feel free to chime in.

Initial thought: I think the control should be near the vars it is affecting. I feel it should be subtle but also not hard to discover.

could someone sell me on this? I'm trying to imagine the value and finding it wanting.

are people really going to the var listing for a story? wouldn't that be better served by a document where you can elaborate more fully, provide context, and fully control formatting and order?

I only have my own context for what I want out of a var listing: predictability so that I can find things. I use search if I'm not quite sure

so there's likely something I'm missing

I'd be super down for it if it was an unambiguous win but it sounds to me, personally, like complication we need to maintain for not much benefit

I'll let @akshat.iitj elaborate, but it is my understanding that some lib authors will order the vars in such a way to tell the story of how to use their lib. It seems @martinklepsch felt this was interesting too as he raised the initial issue.

Personally, I do the story telling in the docs.

yeah, it seems a better fit for prose

But... maybe certain APIs would be better served by line sort order. Especially when the API is always used in a certain order.

would there be a way to make this minimally disruptive to the codebase?

maybe set the preference in a cookie and use that? would it need to be by project? cookies have a max size.

I view the detailed namespace page as a story-teller in text & params, without the code. So, just like how a source-code file tell a story as you read it from top-to-bottom, I expect cljdoc to narrate the story in same order. Take an example of dead-jobs namespace of Goose. As an author, I would rather have size -> find -> replay -> delete.

I usually read clojure files in reverse order

usually the stuff at the top is more helper-y, functions that support stuff later in the file, I've found

Going back to first principles, I'd like to understand why alphabetical ordering was chosen over order by line-number?

because in a user interface that is predictable

there was no search then

moreover is follows other api docs in this regard, and making ui predictable by following common patterns helps users, especially ones dealing with accessibility issues

> I usually read clojure files in reverse order So if cljdocs are ordered alphabetically, this convenience will disappear. Hence, my requirement for sort by line number

And it is also the defacto for doc tools, codox, autodoc, quickdoc.,

also I want to be totally clear here, I am completely unheated in this conversation and not trying to just shut something down because it's different. I'm really coming at it from a value and cost perspective

I like that

> it is also the defacto for doc tools, codox, autodoc, quickdoc I view cljdoc as a Wiki. Since you can choose ordering in a Wiki, I think it'll be nice to have it here as well

the cost right now is very hand-wavey and perhaps it's so small that even value for a subset of people is good enough to include it

I don't think cljdoc is a wiki

now that's a super interesting perspective, viewing it as a wiki

It aspires to be a wiki, that's why cljdoc.edn & doc folders exist IMO

I understand the desire for control over your documentation

would you be willing to put together a prototype of what you're thinking? like where to put the toggle, where you think changes would need to happen?

nothing too very involved

you don't need to do a full implementation or anything

trying to get a sense of how much effort to create and maintain it

two authors have wanted it now

which isn't a ton, but we're a small enough community that it's a larger percentage

I think having search now makes this more palatable

you don't have to only rely on alphabetic order in order to find vars now

It would be nice to hear from@martinklepsch on this too (if you have a moment Martin, if not that's fine too, https://github.com/cljdoc/cljdoc/issues/89 for ref).

> put together a prototype of what you're thinking? like where to put the toggle, where you think changes would need to happen? Sure @corasaurus-hex @lee. Please give me until a week or two.

If you think of API docs as the searchable index (like in the back of a book) and your docs as telling the story, does that make your desire for this feature lessen @akshat.iitj?

Thanks for your valuable time & insights 😄

I view API docs also as a story-teller, hence my need for the feature

> I view the detailed namespace page as a story-teller in text & params, without the code.

Ok, that's fine, just checking.

Thanks for chiming in @corasaurus-hex, much appreciated!

also pleeease pay special attention to having the setting persist per library, and how to store that for someone, and how to use that. we all know clojure can slice and dice data structures but storing preferences is hard

and also I wonder if storing it in the cookie would mean we need one of those cookie overlays

GDPR is a pain

if we decide to just make it part of the query string, that would be fine, too, I think

but in order to store the preference client-side-only you'd need to store it in local storage and then redirect on page load when the query string is missing and the user has selected that they prefer that order

not storing the preference and making them click the toggle every time would be the 80/20 on this feature