"Friction logging" is a form of user experience testing, where you step through a given process and provide insight into your thinking and feelings at various points throughout. The goal is to identify things people with less familiarity with your product / feature might trip on, so you can smooth out your overall experience.
The Founder of a product called Val Town put a call out for this kind of feedback:
Simon Willison pointed out that this was a pretty cool thing for a Founder to do, and I agree, and moreover I also had very important financial paperwork to procrastinate on 🤣, so I decided to dive in and write up my findings.
(Folks familiar with my time as a maintainer of the Drupal project will remember WebChickTestCase alongside every UI change, this is more or less that. I deeply apologize to Steve in advance. 😅 This all comes firmly from a place of love. 💖)
TL;DR
I am a web developer with 20+ years of experience, but limited knowledge of server-side functions / JS.
I purposely did zero reading on any of this in advance, in order to test the onboarding flow “uninfected” by prior background knowledge.
In the end, despite several attempts, I was unable to get one of your simple examples going, due a combination of outdated docs and PEBCAK (probably).
I was also missing the “why” of your product—what use cases it solves, in what situations I should use it, etc.
Time spent: about 2 hours
Feedback Key
✅ Like this! This step was quick and easy, or it was particularly nicely done.
🤔 Things that make you go “hmmm” / things that were a bit confusing
😡 Things that were a significant barrier and/or make you want to throw a table ;)
🗳️ A concrete suggestion on improving something
Home Page
🤔 At first glance, I am intrigued, though by the end of this section it looks like a bit of word salad, because I can’t possibly understand how all of these words go together into one concept. 🤣 I imagine this will change through the course of this exercise.
✅ I like that the intro is short, and “Get started” is right at the top. I proceed to completely ignore the rest of the page. ;) CLICK!
Sign Up Page
https://www.val.town/auth/signup
🤔 You jump straight to asking me for credentials, how about giving me a bit of context here as to what I get out of filling out this form?
(I realize this info was probably all back on the home page, which I unceremoniously skipped, but presumably you’re going to drive traffic to this page from various content/emails/etc, so the point still stands.)
🗳️ Suggestion: The page would benefit from an abbreviated “why” at the top, like:
“Val.town smooshes your smeeshes with great features like:
Boos your bars
Foos your bazzes
Waddles the very highest of woodles
Find our more in our [LINK]about the product page[/LINK].”
🤔 I don’t know you well enough yet to trust you with tying your service to my GitHub account, so I’m going to go the email route. If you want me to make a different choice here, maybe disclose upfront what permissions you want out of that relationship.
✅ I like that the form is short, and you’re asking for very little info up front.
Onboarding
Handle/Newsletter
https://www.val.town/onboarding/handle
🤔 No email verification? Interesting.
✅ I really like the ability to read the newsletter first before deciding to subscribe!
✅ Also like that it opens this in a new tab so that I don’t lose my place.
🗳️ (nit) Put a space between “month.” and “Read” ;)
🗳️ The link goes to ALL blog posts, vs. just the newsletter ones; it might be nice to filter by tag there, but it might also be that this is “by design” so I see a fuller picture of the stuff you’re talking about.
(Detour) Newsletter Sample
https://blog.val.town/blog/val-town-newsletter-15/
✅ Like how visual this is, and also how skimmable it is. Scannable emojis are great.
✅ Like the casual humour (“foot gun”), diagrams to help explain complex concepts.
✅ This random screenshot also showcases that you invite user feedback on your product, nice! :D
How did you hear?
https://www.val.town/onboarding/referral
✅ Good idea to ask this question.
✅ Also like that it is skippable in case I’m not feeling it.
Sample code
https://www.val.town/onboarding/val
✅ Neat that there’s a sample preview of some stuff ready-to-go.
🤔 Why am I “indigoGecko” and not “webchick” when I already gave you my username?
🗳️ Ah, I figured out later that this is the name of the code snippet. Maybe default it to something less silly then like HTTPResponseReact1 or something.
🤔 I'm very sorry, but I still have absolutely no idea what this is for, why I would use it, and how I would use it.
🤔 There is a "Want details on what each line of this code is doing?" link, which is nice, but that is a bit too granular for my current phase of understanding. The code is not particularly un-easy to read, I’m still missing the “why” and “what do I DO with this nice chunk of code now?”
✅ However, I now know there’s a Discord I can go to to get extra support if I need it.
🗳️ Maybe consider making the Discord community's existence more prominent?
🗳️ I notice when I edit text above, I still need to manually click “Preview” to show below, and there’s a small pause while I wait for things to reload. Would be neat if this happened “live” instead. (I also would like a rainbow-farting unicorn, please ;))
🤔 Not sure what the point is of the { headers: { "Content-Type": "text/html" } }, line, because when I changed that to "text/json", nothing happened.
Anyway, ok. Clicking DONE!
Main Interface
🤔 Ok, looks like I can create different kinds of “vals” here, and organize them into folders. What are “vals” and what are they for?
🤔 Ah, looks like if I scroll all the way to the bottom I get some of this info:
🗳️ Suggestion: move this to the top, maybe in a collapsible section so people who already know their way around can get the compact interface.
✅ “Templates” is nice. I like all the copy/pasta examples so I could find something close to what I want and modify it.
🤔 Is there a way for the community to contribute to these as well?
🤔 Ok, that said, my prevailing emotion right now is “feeling lost on what to do next,” so I’m going off to Docs in order to see if I can find some kind of “Quickstart” example that takes me through “soup-to-nuts.”
Docs
🤔 Skimming the home page and the left sidebar, not really finding what I’m after. Let’s try “Guides.”
🗳️ Guides is WAY far down the list; maybe think about moving it up.
🤔 Hmmm. Not sure, this all seems pretty low-level and seems to assume I know more than I do.
Ok, well. One very basic web thing that all web developers need to do is save HTML form data, so let’s try that.
Save HTML Form Data Guide
https://docs.val.town/guides/save-html-form-data/
✅ Nice! This looks more like it.
✅ Like that both video and written content is provided.
🤔 They are not, however, equivalent. (Maybe that’s “by design” as well.) — the video does more of an overview and the text is more pragmatic, copy/paste.
🗳️ This very video or something similar to it, ought to be on at least the docs home page, if not in the product itself. In about 30 seconds of hearing you talk, I “got” it; it being “Adding dynamic stuff to static websites” is at least one use case of your thing, and it's good at integrating stuff to/from other places. 🙂 (I would greatly welcome insight on others!)
🤔 Interestingly, when I try to do exactly what’s outlined in the video, it looks like I can no longer submit feedback on the docs, there is instead an “Edit this page” and it takes me to GitHub where it prompts me to fork the repo to suggest changes.
I can understand this being more useful to you as a maintainer, because it encourages people to solve their own problems (and probably also cuts down on a bunch of e-mail spam ;)), but just pointing out that at this point in the journey I would just bail here without giving you any feedback because that just seems like way too much work for as a drive-by docs bug spotter. ;)
Anyway, let’s continue down the tutorial.
(Attempting to) Add an HTTP val
✅ I like that I can just copy/paste this with a handy button.
🤔 It also says I can “fork the one below” but I don’t see how I to do that. Maybe this is only an option I get if I auth with GitHub, but then it would be nice if either this text didn’t show up at all, or it mentioned that was a requirement.
🤔 Now that I’ve copied it, to whence do I paste it? I’m guessing this is back on the other “main” page where I got confused and went to docs. It would be nice if something here said that. (But maybe this is just knowledge other people innately have and unnecessary.)
Anyway, I go back there:
🤔 Here’s an interesting thing. You told me in the docs that I needed an HTTP val, but HTTP val is not one of the options in this list. (Maybe you mean HTTP handler?) Nothing under “Templates” says “HTTP val” either.
Ok, so since nothing matches, let’s try “New val”
🤔 Hmmm. Ok this is a TOTAL blank slate.
🗳️ It’d be nice if there was some skeleton code or even some commented out stuff that’s like “You need at least a Request and Response object here” or… anything.
Anyway, let’s paste in the code from before and click “Run” and see what happens.
🤔 Hm. On the surface, nothing at all happened. Down below, there’s no “Awaiting connection…” message or “Error: You done screwed up, son” or any output whatsoever, beyond a counter that keeps counting up and a green light. Assuming this is a good thing and expected?
(Attempting to) Create an HTML form and link it back
Back to the tutorial, copy/pasting the form to just a local form.html file:
✅ The video made a big deal about the importance of the form action attribute. I see that you call it out here as well, both in the text above and in a comment above the code.
😡 However, the instructions here don’t seem to work. There is no menu called “Endpoints,” there is a Copy under the “three dots” menu, but “web endpoint” is not one of the things I can copy.
✅ That said, I like the preview of each copy option here, because that at least narrows it down that I probably don’t want “Val ID” but rather one of the link/URL ones.
😡 Now to iterate through to find the value that’s closest to the “https://user-saveFormData.web.val.run” in the sample code:
Module URL: https://esm.town/v/webchick/tomatoPossum
😡 Well, *&^@#. ;) NONE of those are anything like the one in the example. I’ll just go with “Link” then since it looks similar to what I usually put in form action attributes.
Let’s try it and see if it works (I don’t think it will, as there’s a third section of the docs that I haven’t looked at yet). Here’s a checkpoint:
😡 There was a “Not found” error upon submission, but it disappeared so fast I couldn’t read it, nor screenshot it. It just took me back to the main page with no message explaining what just happened.
(Attempting to) Tie everything together
All right, let’s see if that last bit of the tutorial ties this up for us.
🤔 Hm. I don’t love this method compared to having the HTML form cleanly separated, but ok.
🤔 Presumably I copy / paste this on TOP of my existing val code (given the green + signs as a “diff”) but it’d be nice if the docs made this more explicit.
Anyway, let’s try that and hit Run again and see what happens now:
🤔 Oh, interesting. There are now TWO processes executing.
😡 I have clicked on every possible thing known to existence on the older one, and cannot for the life of me figure out a way to stop it.
🤔 Welp. Let’s copy the link into a new browser window and see what happens:
https://www.val.town/v/webchick/tomatoPossum
Nope. ;) That’s just the same pastebin kind of thing. I guess this is the Gist-like “sharing” bit of the product.
🤔 Ok, let’s try copying the module URL:
https://esm.town/v/webchick/tomatoPossum
{"statusCode":404,"error":"Not Found","message":"Sorry, that Val could not be found."}
OK, that’s at least something I can debug! :D
🤔 Is it because I never “Saved” the val?
✅ No, Save is grayed out; apparently it autosaves (that’s nice).
🤔 Is there anything in logs?
https://www.val.town/v/webchick/tomatoPossum/evaluations
🤔 Ok, says there are 19 log entries, that could potentially be useful? But when I click it...
😡 Hmmm. But where do I see the log entries? "Logs" is blank, despite saying there were 19 of these on the screen before.
🤔 Ah, if I click a teeny tiny checkbox called “System” I can see stuff in the Logs, but this appears to just be pulling in dependencies, so not helpful here.
🤔 Ok, trying one last thing, which is to go back to my locally hosted form.html and change the form action to the module URL instead of the link url.
😡 LOL nope. Welp, I officially give up.
Conclusion/Recommendations
It’s very possible that this product is NOT for people without extensive server-side function / JS experience, in which case fair enough; this feedback may not be valuable to you.
However, consider that by adding a few sign-posts along the way, and making a concerted effort to drive new “what’s this then?” users towards a seamlessly working example at the beginning of their journey, you could see a huge uptick in usage from people who know web development things really well, and could start to see the power of using your thing as well. 🙂
Here are some specific recommendations:
Add more of the “why” on your product, from both within the product and especially during the onboarding flow—what use cases does it allow me to solve, what day-to-day headaches can it remove for me, and why is it better to do this with you than alternative vendors, etc?
In the product interface, think through how to guide a new user, as quickly as possible, toward seeing the “ah-ha” value of your product. It looks like you have some good tutorials, but they’re a bit buried and not integrated into the product itself.
Perform a docs audit: Take a swing through your docs and make sure they reflect changes you’ve made to the UI since writing them. (e.g. which “Copy” do I use?)
Hope that helps! 😀
Also, dear reader, if you are at all interested in me doing one of these for your developer-oriented product, hit me up at friction -at- webchick -dot- net.