A first-timer's experience with the Table Builder

I was trying to create a table here on the Discourse meta a couple of days ago and was really struggling. Since I wasn’t sure how the builder is supposed to work and what I saw wasn’t what I was expecting, so I just added the default table and customized it from there.

I thought I might share some feedback now that I’ve spent a bit more time and figured out most of what I was missing.

My first table builder experience

I’ll be honest, the table builder is far more advanced than I was expecting - so great job on the work y’all have put into it. Most platforms that allow tables keep builders fairly simple and just give you a quick way to indicate the quantity of rows and columns you want in your table. This creates a pattern you can follow. That said, I haven’t found a lot of platforms that use Markdown that offer table builders.

I think it’s great that you have an actual builder that gives something more like a WYSIWYG experience rather than relying on people getting more comfortable with an (admittedly) un-friendly markdown experience. I’m able to create tables in MD manually but trying to review them is nearly impossible without a preview.

Unfortunately, I started using the tool expecting to just tell it “I want a table with five columns and ten rows”… and that’s not what I got - instead, I got a big white page with a mostly-empty table. There wasn’t any info about what I was supposed to do immediately visible to me so I was a bit lost. What you have here is something very similar to how Google Docs inserts/edits tables but there’s not a lot in the UI to cue the user to that.

The first thing I tried to do was double click the “Column 1” text since that’s always where I start with tables - naming rows/columns. No dice. I could select the text but nothing would remove it. Because I was in the mindset of the plain text tool of the standard Discourse post creator, I didn’t even think about right clicking.

I did discover that I could add text to the individual cells but I was still lost when it came to adding/removing rows and columns because I was still in the mindset that all I was doing was telling a simple tool to create the framework that I’d then have to edit in the standard editor.

Since the main point of frustration for me when creating a MD table is remembering how to set up the first two lines of code (header and horizontal divider), I clicked the “build table” button at this point and just edited it directly.

Today I returned because I couldn’t actually figure out if the troubles I ran into were a bug, UI/UX, or PEBKAC and wanted to report a bug, recommend a UI change, or figure out how I’m such an idiot to miss something so obvious.

In the end, I found it was probably a combination of all three. There are a few minor issues I’d classify as bugs, a few UI/UX issues and, because I didn’t open or notice the “?” in the lower right corner, at least a bit of my own fault.

UI/UX improvement thoughts

There are several things I’ve hinted at above that would really help escalate an already awesome tool by making its features more findable. The main way I think this could be improved is to really help users understand how to use the builder.

Make instructions more discoverable.

While you do have that question mark icon in the lower right corner, it’s so far out of the way of the main page content so it’s very easy to miss. The help icon could be much more visible if it were somewhere else on the page - like right next to the header. You could consider popping the modal open the first time someone uses the builder and give the option of dismissing it from future visits. Alternatively, there’s not actually much text in the help menu - consider whether it makes sense to hide it at all - display it directly above or below the table.

Use visible and familiar UI elements to improve feature discovery

You have the drop down arrow already to indicate sorting by a specific column - do more of this to make the other features easier to find rather than hiding them in right-click menus. This also helps make the builder more mobile-friendly.

  • Display the edit icon in header cells to make editing the text more discoverable.
  • Use a + Icon at the edges of the table to quickly add new rows/columns.
  • If entire rows/columns are highlighted, add a trash can icon above the rows or left of the columns to indicate they can be deleted.

I’m not a UI/UX person so there are probably more standard options here but I hope this list gives y’all some ideas of how to do this. I think finding the right middle ground between how the table builder in Google Docs works and what you have now would lead to the tool being more intuitive without needing help text.

Make it feel like an editor

While I know MD tables are much more limited in the formatting options that can be used, the page is really missing any indication that it is an editor. Having a bar that lets you add rows, columns, and what formatting is possible would elevate this tool while doing more to hint to users what it is and what they can do. Right now, I’m not sure how to add text decorations, links, images, etc to a table. These are all possible but not in the Builder.

A few tiny bugs

  • The first column within the editor confuses me. It leads me to feel like you can have row headers, which simply aren’t possible in MD. Consider adjusting this to make it clearer that these will not appear in the final table.
  • The completed table MD doesn’t have the extra spaces in front of the text in the first column’s cells. This doesn’t seem to break the table but I’d love it to be consistent.
  • Consider automatically placing the completed table on a new line. If I build a table on an existing line of text, it looks broken. By forcing it to be on a new line with an empty line above it, the table will always work properly.

Here’s a screenshot that shows the second and third items.