Commands Documentation Update


#1

I don’t see a unique category for site feature updates, but this does pertain to bot usage.

Right now the commands list ( https://phantombot.tv/commands/ ) defaults to only listing 10 entries.

This will force the vast majority of users to update the “show entries” dropdown to pick something more practical. I find myself doing this every time I want to browse the commands list. I always select “5000” since “All” is not an option.

10 commands per page is really not a benefit to anyone, all it does is force more user interaction. At a minimum it should be something like 100.

/Chris


#2

No one else here is really complaining other than you. 5000 commands is essentially all, since there will never be more than 5000 commands. I really don’t see a need to change the code, considering most people (I’m assuming) that are looking for a command would most likely just search for what they’re looking for.


#3

Hi @Zelakto,

I’m not complaining. I’m offering a constructive suggestion to improve the UX for the commands list, and siting a specific challenge that I, a user of the product, routinely face when using this resource.

The issue is that there is no real value added by limiting the command list to 10 results by default. Even on a mobile browser 10 is unnecessarily limiting. So why not improve the user experience by making the default display mode more optimal?

I do agree that many people (myself included) use the search functionality on the commands list page, but I can say from personal experience that the majority of my own use of that resource is browsing large blocks of commands related to a specific function, and I’ve found search does not always work for that.

Since the commands are the primary interface for the bot, I would hope there is not resistance to possibly improving the single location where all users review those commands.


#4

So, my two cents, developing enterprise HR solutions. The company that provides that HR software that I develop for has spent a lot of money on UX research, and the screens that we deal with are all made to fit within a small space – essentially mobile or a 12" MacBook screen. Tables are designed to fit within that space and offer all controls so that a person doesn’t have to scroll to reach the controls. Scrolling is a no-no with large data sets, they are to be presented within tables that are easy to navigate. No HR representative wants to scroll through 1000 lines of history on a worker, for example. The idea is to present everything in a small space, for research purposes with controls readily available. When I have spoken with Joe Blow users that use the software, they are very happy with the way that data is presented compared to other systems.

The command screen is designed that way as well. The idea is to be able to query on a command, find it, copy/paste into chat, and have the space to do that if you are running on a laptop (I monitor my VPS bot from a MacBook Pro) or have multiple screens and are using one for gaming and another for monitoring the bot.

I get that displaying everything on a page may make sense, but, the modern UX design principles shy away from that, at least, at the places where I work and have worked.

Cheers


#5

Hey @IllusionaryOne! :smiley:

I’m a UI/UX professional as part of my day job and also consult in that space. I completely understand and agree with your point. Long scrolling data sets are ideally avoided, but the issue of initially hiding data from users is also equally problematic. When it comes to UX I like to equate user actions (scrolling or clicking) to a form of currency, and think of every user as having a limited budget before they throw in the towel. The fewer actions you can put between a user and their end goal, the better. While both scrolling and clicking expend the user’s budget, clicks are far more expensive than scrolling. Scrolling is a near-passive action and clicking requires more focus and typically evokes a UI state change that requires some adjustment.

The challenge here is that the entire data set is overwhelming for “typical” users (lots of scrolling), and a data set parsed dow to only 10 items is too limited to be of practical use to nearly any user (prior to searching). In my current gig I’m dealing a lot with reporting and analytic software, and I find most data grids default to between 50 and 100 items per page. I think we just need a goldilocks compromise in the UI to increase its usability. That sweet spot should be somewhere between 10 and 5000 :wink:

As an exercise I took common terms associated with bot usage (tip, poll, raffle, mod, playlist, request, game, twitter, etc) and found that in most cases the results were between 15 and 80 items. Meaning to find a specific command when limited to a listing of only 10 items, almost every case would require multiple user interactions (beyond the initial search) to consume the results.

Then there is the case scenario of a user that is new to the bot wanting to review the entire list, as for many users (myself included) reviewing the commands is the first glimpse into the full functionality of the bot. With a limited set of 10 commands per page, and the pagination UI at the bottom of the page, a user on a smaller screen/window would have to read down the list, click the next page, then scroll back to the top of the list to view the first item on the new page. This means the initial goal of reducing scrolling by limiting the results may actually require more scrolling, as users have to scroll down and then back up to review next 10 results.

Future versions of the command list could offer filtering based on command level (admin, moderator, user, etc) to help narrow the data set based on use case scenarios. I’m sure there are other great filtering options that could be implemented based on different modules or functionality types as well.

I’m an avid supporter of PhantomBot (best damn bot out there!) and just want to help make using it (and the supporting resources) as easy as and intuitive as possible. Having been frustrated by the command list on many occasions I figured it was a good time to finally post something about it. I’m not saying the command list is bad, but there’s always room for improvement! :smiley:

Thanks,

/Chris


#6

I see what you are saying, I think that there are different philosophies depending upon the company that has the ownership of the UX. Where I do my work, the HR system is managing companies with over 2 million employees – large datasets, especially when you start drilling into “events” for those employees. The way that I described is how they chose to deal with it.

What I was discussing with Zelakto is looking at adding a feature that I like from the product that I do a lot of work on – a CSV [Excel] export button – which I think would be most beneficial to allow folks to get the data down and view/sort/search as they see fit too without the constraints of a web interface. Thoughts on something like that?


#7

I’m always a fan of allowing CSV exports on data grids, especially if there is value in generating reports/tools around the data.

In this case I think an export would be useful, but I would be weary of expecting too many people to use an external application as a way to more easily navigate the data, since that is usually handled at the source (the page).

I see the value in a CSV export being more for folks that would want to take the command list and process it for display on their own site or something to that effect.

It would be awesome if the dataset had a column for each command that contains its default user level (streamer, admin, mod, viewer, etc). Then you could easily filter the command list based on the end use. An example of the value in this would be a moderator (not the bot owner) could then use the command list and see what commands are typically available to them, as could an admin who does not have streamer privileges, or even a regular viewer. This way the phantombot.tv site becomes a resource to anyone using the bot, not just bot owners. That would also help increase awareness and potentially lead to more users choosing PhantomBot for their own streams.

For example, right now I’m sending my viewers/mods/admins to this page(still in development) to see some of the commands available to them. But if I were able to link out to an access level filtered phantombot.tv page for core bot commands I would not need to list as much on my own site, and users would get more exposure to the PhantomBot brand.

At work I’ve been using the jQuery plugin “DataTables” a lot for internal tool development. We do a lot of custom reporting that requires sorting/filtering/searching/CSV export, and it’s nice to have that handled on the client side, since we can turn new custom tools around really quickly. DataTables is pretty robust and easy to use, and I’ve found a lot of value in it. That said, I’m always curious to see what other folks are doing for their UI. What is currently handling the pagination/sorting on the commands page? It looks nice and clean (as does the whole site), so I would imagine it includes filtering options as well.

/Chris


#8

Hey,

I’m by no means a UI/UX developer, not even close to one, but I did gather experience over the years of working on PhantomBot. Now, I do see valid points in both your comments and @IllusionaryOne’s, but you have to remember that it is hard to make everyone happy, some might like the commands table like it currently is, some might like your idea better. From all the support that I’ve provided over the years for our control panel, one common things I’ve noticed is that a lot of users forget to scroll, this might seem silly, but it has happened numerous times.

My opinion doesn’t mean much here, but I do think being able to select the amount of commands to be shown on a page by the user is a good thing, rather than listing all of them. Currently we only have about 300 commands, if we did have over 1000, showing all of them on one page might start to lag lower-end computers on the page. From most tables I’ve seen, whether it be for a bot, or something else, the range always seems to be around 10-15 per-page. Ten seems to be the default for jQuery’s datatables. I know that changing the default list page, or list amount is extremely easy, but that’s not up to me, it’s up to Zelakto.

The ability to create a CSV (Comma Separated Values) file seems to be a great idea, if I were to implement it, it would probably be a console command that a user can run, or maybe even have it as an endpoint in our API, and it would generate a list of all bot commands, including custom ones with their permission and module name.

Those are my thoughts on this, not that anyone cares, but I just thought that I would share. :slight_smile:


#9

The more thoughts the better! :smiley:

I agree that you would not want to show all commands by default, but I think 10 is just too low for any use case scenario I can come up with. Most command searches I performed result in more than 10 commands, and using the pagination UI is best to be avoided if possible, as having to scroll down and then back up is cumbersome if you are on a screen size where all 10 do not show above the fold.

If this is using the jQuery datatables plugin, it supports CSV exports. A lot of the tools I develop around it are designed to export a CSV based on user filtering and custom data ranges for reporting/analytics.

/Chris


#10

Just created a bot command that will allow you to export commands for modules that are enabled, this includes custom commands. Doesn’t have definitions, that would have to be implemented another way. Might not be what you’re looking for, but maybe others can make use of it.

createcmdlist
[09-19-2017 @ 17:57:12.146 ADT] [CONSOLE] Executing createcmdlist, this can take a bit of time.
[09-19-2017 @ 17:57:12.229 ADT] [CONSOLE] Command list has been created under command_list.csv


#11

That’s great! Would it be possible to have the dbquery API calls pass the permission value along as well?

For example right now I’m using “/dbquery?table=command&getData=${key}” in the script I run every hour to upload bot JSON data to my web server to list comands/etc. Would be amazing to be able to have that data include the permissions level. What’s the table name for the general non-custom commands?

/Chris


#12

Which folder is this exporting to?


#13

Hey,

I just updated the command list page, it may be cached on your end, so try a hard refresh, but let me know what you think!

Thanks,
Zack