Structured content first: Why you should consider writing JSON, even if your prototype is disposable
(Spoiler: over-the-top nerding pays out, big time)
Over Easter, I had time to really get my nerd on. Like, even more than usual. It was both fun and profitable.
What’s JSON?
JSON stands for JavaScript Object Notation. It’s a human-readable way of listing out arrays of content which can also be parsed by code. An example:
{
"event_calendar": "Easter Sunday",
"event_calendar_date": "April 1, 2018"
},
{
"event_calendar": "International Workers' Day",
"event_calendar_date": "May 1, 2018"
}Here, event_calendar is an attribute that I can reuse with as many different values (here, dates) as I care to list. I’m just making up that attribute name, by the way. I could have called it frog if I wanted.
(Sticklers will note that I’m not using correct JSON date formatting here — I just needed something human-readable to feed into my UI mockups)
The thing about JSON is that it forces you to think about specific examples of your content, and how that content is structured. For example, a calendar event is probably a different kind of thing from a message, which means that they probably have some different qualities. You want to send a message wishing someone Happy International Workers’ Day? Great — then that message has to be sent at a particular time.
{
"event_type": "calendar",
"event_calendar": "International Workers' Day",
"event_calendar_date": "May 1, 2018"
},
{
"event_type": "message",
"event_message": "Happy International Workers' Day!",
"event_message_date": "May 1, 2018",
"event_message_time": "9am"
}And just like that, we’ve written some content. Exactly what I needed when I had three days of mobile web app prototyping ahead of me, while my client and my colleagues were on holiday.
1. Write JSON when you’re working in Sketch
My original motivation for writing content in JSON was to be able to design with real content, because anything else is nonsense. Did you know you can auto-fill Sketch with stuff from (among other things) JSON files? Neat, right?
I mean, really that plugin is really there to help you make use of existing JSON data, but I wanted to see what the app would look like with (say) 15 calendar events listed, or when you’d received 15 messages. But those things didn’t exist anywhere yet, so I figured I’d just write them out myself.
2. Write JSON when you don’t have any content
It sounds obvious, but in order to be able to pull a list of 15 calendar events into my Sketch file, I had to write out 15 relevant calendar events in JSON. The same with messages and tasks. Doing this forced me to think about what objects actually existed, and what kind of content defined each kind of object. Calendar events need titles, dates and times, and maybe sometimes additional information about what is happening. Messages need to show the date and time when they were sent. Tasks on a to-do list need calls to action, and something to indicate whether they have been completed or not. And that’s before we get into all the possible interactions between these different types of objects in the UI.
Doing all this gave me a much better understanding of exactly the things you want when you’re designing a UI than I ever would have got by just working in Sketch. In other words, I went straight to the good stuff: all those content-related questions that inform information hierarchy, navigation, actions, and user flow. Lovely.
3. Write JSON when you want a better grasp of user stories
We already had a shared Trello board with the client, showing content and functionality for the web app at different stages of the user journey. User stories on the board typically ran at the level of “do offline task that involves agreeing a calendar date, then later, receive a message that the date has been confirmed”.
What I actually wanted at this point was to extract the cards from Trello as JSON, and tidy that up. But while you can export a Trello board as JSON, nobody who is not a coder can make sense of the soup that Trello spits out into the browser. Really, I just want the columns of cards and their contents, not several thousand lines of extra nonsense. Plus I wanted to be able to reupload the JSON file to Trello afterwards to update the board, but that isn’t currently possible.
So instead, I used our Trello board as a reference to work systematically through my own JSON file, creating tasks and calender events and so on in response to user stories. This turned out to be really useful, because I found quite a lot of incomplete bits in our Trello descriptions that we hadn’t previously picked up on when working through them with the client. Things like, “here we are clearly going to have to send a message to say that Event X has happened”, and “Event Y clearly belongs to phase 4, not phase 3”.
Again, working through this in JSON forced me to consider all the actions and occurrences surrounding an event, not just the most obvious ones. So by the time I was finished, I didn’t just have a JSON file — I also had a much more complete backlog in Trello. Having a tighter grip on all those user stories makes everything easier, from estimating development costs to knowing what content you’re asking the client to write.
4. Write JSON when you don’t have a way of sharing content
Inevitably, as soon as I started importing bits of content from JSON into Sketch to populate my screens, I wanted to tweak them, because that’s what happens when you finally see your content in a real context. So of course, I started editing content right there in Sketch. But now the content in my JSON file was out of date.
It sucks to trap all of my best thinking about content in Sketch. As soon as I spit out a clickable prototype or PDFs for colleagues and clients to look at, that content stops being pastable and reusable, and it no longer all lives in one place. If my developer colleague wants to find and use the content I wrote, she’s looking at error-prone copy-typing or cut/paste. If a client wants to propose tweaks or improvements to content, they have the same problem. Some of the content I wrote in JSON wasn’t even visible in the mockups, but it seemed silly to waste it.
Ideally at this point I’d have exported the entire Sketch file as JSON: all the updated content back in one file. In a perfect world, assuming I’d made sensible use of symbols and overrides, it could work. I tried Sketch Exchanger, which does import reams of metadata from Sketch, but not the stuff I want (nested symbols and objects with their respective override texts), and doesn’t do it in a way that’s easily accessible (more soup). I also found sketch2json, but it was heavily developer-oriented and I got stuck trying to use it.
But what if a simple JSON file was enough as a “single source of the truth” for content? Good enough to communicate how I’ve structured events and objects, and a single place where everyone could find, reuse and edit content? Hell, it’s such a simple file that I could send it to the client for them to edit the content themselves (I can always tidy up afterwards if need be). So I went through the JSON file and copy/pasted the updated content back in from Sketch. This was a little fiddly, but not very (symbols + overrides FTW), and there was actually relatively little to do.
I’ll be honest: as originally written, mine was a very flat and poorly-structured JSON file. I thought about listing all the calendar events first, and then all the notifications, and so on, but figured I might make lots of mistakes/omissions while working through the Trello board, which is structured in chronological order around the user journey. But the concept of a ‘user journey’ only exists in the data as attribute that defines which phase something happens in, nothing more detailed. And structuring any document based on something that only existed in my head seemed like a terrible idea.
In the end I decided that organising events and objects by phase and then by type would be the least confusing for my colleagues and clients. Humans can come unhinged if you take all the chronology away from a story.
Was it really worth it, doing all this?
I learned a lot. I improved our the backlog, I prototyped a UI based on real content and real user tasks and situations, and I created something that communicated lots of different aspects of my thinking to colleagues and clients who were not around when I was doing that thinking.
Could I have used some other system than JSON to get the benefits of a systematic approach? Probably; there are aspects of Test-Driven Development or even Getting Things Done that could be applied here. But neither of those processes produces output consumable by Sketch, as far as I know :)
Yeah, but this is hardly new.
I make no claim that this is a novel approach. I just stumbled on it through a combination of dumb luck and having three uninterrupted days to think about the problem. If you do this already, good for you; now it’s become a thing I do, too. Plus, you never know — maybe some version of the JSON I wrote really will make it into a code prototype, or even production.
Funny story: it turned out almost not to be worth writing JSON for the sake of importing into Sketch, which was the only reason I started this in the first place. There were surprisingly few things in our version 1 backlog, and I could probably just have written them by hand in Sketch. And then when I had written and imported my JSON file into Sketch, I quickly found a bug that made Sketch layers disappear when trying to link them to JSON elements, so that was kind of a bust. But Invision (who make the Craft plugin for Sketch) were super quick to get back to me about the bug, and we’re working on it. And I would still write JSON next time, because the process of doing so was so damn useful in every other regard.
