Document how to use in practice

[nirvdrum]

I've watched the LexoRank video linked from the README, but I couldn't work out from either the video or the README how to best use the library. When reordering an item, calculating the new rank seems pretty straightforward. But it's not clear to me how to get going with a brand new list.

As far as I can tell, you want to do something like:

const firstItem = LexoRank.middle();
const secondItem = firstItem.genNext();
const thirdItem = secondItem.genNext();

But, that "wastes" half of the available rankings for the extremely unlikely event where the entire list gets reversed. But, the first Item can't be LexoRank.min() either, or you'd never be able to put something before it. I guess it could be something like LexoRank.min().between(LexoRank.middle()) or maybe LexoRank.min().genNext(). Maybe there isn't a right answer for this. But, any guidance the document could provide would be much appreciated.

In my particular case, I append items to a list by default and the user might opt to re-order the list. I expect reorderings to be relatively small and infrequent, so my primary concern would be exhausting the default space by cutting it in half each time a new item is appended.

[shobokshy]

@nirvdrum if you set up a new instance of JIRA core, the very first issue you create will get assigned a rank using LexoRank.middle() "0|hzzzzz". Then subsequent issues get ranked using genNext().

[nirvdrum]

@shobokshy Thanks for the info. It's a bit surprising to me, but useful nonetheless.

[shobokshy]

@nirvdrum I think it's because the rank field in JIRA is a global field per instance, so that allows you to view issues from different projects all on the same board, and users might re-order the issues to the top.

So for a single board it might not be common scenario to move issues to the top of the first created one, but when you look at the whole instance it probably common, therefore they start at .middle()

Anyways I am just speculating.

[shobokshy]

@nirvdrum another thing I noticed is when you have two issues for example and you swap their order around they dont use .between() but they just swap the ranks from the two issues.

Don't know if this makes sense

[trydalch]

It would also be valuable to give examples of detecting a rebalance and the use of the bucketing feature is done.

Not that I absolutely need it, but it would also be valuable to have an eli5 example of how to use this library. Would lead to quicker and probably wider adoption.

[trydalch]

Documenting how to change the base would be valuable.

[kvandake]

Hello!

Thank you for the feedback. I will try to find time to write detailed documentation.