 Okay, hello everyone. I'm gonna get started. I have a lot of stuff to talk about so people can keep coming in, go for it. It is late on the second day and I'm already seeing the 50 yard stairs in the hallway. Everybody got another hour and some change in them? Yes? Excellent, excellent. I think I do too, so that's good. All right, who am I? Hello, my name is Susan Prosser and I am primarily a file maker developer but I was trained as a writer actually and some of you may know me from the fact that I do professional writing. I have, along with my excellent co-author here, Stuart Gripman, have co-authored seven books about file maker, the most recent and the last of which is the 14 version. And I wasn't gonna mention this but a lot of people have asked me in the halls and sadly O'Reilly has discontinued the missing manual series except for the David Polk so it is the last file maker missing manual title. Oh, thank you. I'm sorry, is that a question? So it's still the latest version, that's the good news and everything that was about 14 is still right. So I've also written three tech briefs for file maker and they're published in the file maker community if your member's there and some of those, one of them is almost 10 years old and it is still current and I'm really proud of that and I've written lots of articles as well. Who are you and why are you here? In the past I've talked, I did a session back in Miami about dashboards and there I talked about the way human beings perceive and grapple with understanding data and in a way this session today is a follow on to that one. I'm gonna talk about something similar. I wanna talk about the way human beings perceive and understand meaning so that we can start to identify the places where friction creeps in and misunderstanding and slowing down of our beautiful workflows. So the end goal is the same with words with meaning as it is with data. You have some information that you need to give to your users and you need to do that in a timely and efficient fashion, right? And we know about efficiency. We optimize code and we talk about architecting tables in a super efficient way and making sure that our code and our systems can run as fast as possible and what I'm talking about today is doing the same thing for the wet wear in our systems the human brains as we do when we optimize architecture and code. So I'm gonna start today talking about some conceptual information and some ways that you're already using communication skills that go way beyond grammar. This is, today this is not about grammar at all. This is way beyond this. But I wanna draw your attention to the ways that you're already using a huge number of communication skills and then we'll later do a series of examples and I'll teach you when communication bogs down I'll teach you how to recognize it and then we'll clean some things up so that you can see how to do it yourselves. But first I wanna start with what I perceive right now is kind of the dark side of UX. There's this perception out there right now and more than a perception there's a specific mandate from project managers where they say that the goal for their software is to make it so intuitive that users don't need any kind of assistance learning software, right? I am all on board for good UX and intuitiveness is something that I strive for but I don't think it's possible to create software that's 100% intuitive and I think that it's probably a mistake to try to achieve it. First, if it's true, it's only true for super simple apps like maybe something that lets you track steps on a smartwatch maybe or maybe something that lets you consume data. But even a web browser which is primarily a consumption device isn't that simple a piece of software. I switched to Chrome recently and the first thing I wanted to do was set up my own custom thumbnails, right? And it's super easy to figure out how to delete the ones they put there for you but nothing that I knew about how software worked or other web browsers worked would let me define my own, right? So I did something that I don't like to do and you might find this surprising considering how much technical information I've written. I read Help and I didn't enjoy it. And the reason I didn't enjoy it is because the answer was not there. What I needed wasn't there and so I had to Google and the answer wasn't on the first page and it wasn't even on the second page and somewhere down and maybe it was a dark web. I don't know, it was in a forum someplace. Somebody suggested something that helped me do something really simple that I'm sure other people want to know how to do, right? So as good as UX gets, anything moderately complex is not intuitive enough for us not to be constantly assisting our users. But even if you sort of hit that sweet spot and you make this perfectly intuitive system that is intuitive to those of us in this room who are technical and inclined to mess with it, there's a large segment of the audience that we tend to forget and these are the people who will never learn software without a lot of help and we forget them and their particular needs at our peril and we do this especially if we're designing for a vertical market, right? Because there's a lot, our custom users are probably somewhat technical but not all of them are, but in a vertical market you have to know that you've got a lot of non-technical people. So it's only if you have a very, very narrow definition of what telecommunications or telecommunicable technical communications are that you could even think about doing away with it and this appear, it represents what most people think of as technical communications. They assume that technical communications equal user guides and that the Venn diagram has 100% overlap and that's all there is to it but in fact it's a really thin sliver of overlap. In fact, our very interfaces themselves, everything that makes up an interface is made up of words. Think how many words are on your interface. Data itself is frequently made up of text and even if your data happens to be perhaps scientific and mostly numeric and you figured out how to do an icon rich interface that doesn't have a lot of text on buttons, FileMaker itself still has menus and there's text all over the place, field labels and if you don't have field labels you've got placeholder text. So I recently read an article that makes this really good case that text itself is our interface, right? And I'm not gonna try to pronounce the name of this writer because he's Finnish and I respect him and I'm gonna mangle it. The link to the article is here on this slide if you wanna read it. But what he says, what he reminds us is that data itself is the content of the apps of the databases that we're creating and then our job is to curate the most important parts of the system and layer that on top of the text and then everything else that we put on our interfaces that we put in our workflows that we show to the user is built on those two things, data and process, right? So here's where we're really sending messages, right? They're in the data we've already said, they are in user guides, they're in maybe short tutorials that we're writing, they're in the names that we give to our schema, we're talking tool tips, we're talking labels, we are talking emails that you send back and forth to the project manager. All of these things send messages and it's just that we're not used to thinking of these things as primarily communication tools. We're thinking of them as the schema or as structure, as workflow and if we change our thinking just a little bit and we remember that they communicate from their core and what they're communicating is highly technical information then it makes it a lot easier to think about how to make that transaction, that transmission of information becomes much more clear if we're specific about remembering how much we're communicating and where we can bring communication skills to bear. So let's start, let's make sure everybody's on the same page and let's start with the definition of user experience so we're all on the same page. So the International Organization for Standards says this, user experience is a person's perceptions and responses that result from the use or anticipated use of a system. So what's important about this is that anticipated use includes all that planning time and all that interaction with the team before you launch, it includes what happens in your service after they've done the first testing, even after launch. So user experience is not just what happens when the user launches the database and enters data and clicks buttons. User experience is that whole broad thing, right? And I wanna be specific that I think that user UX definitely includes any misuse due to misunderstanding or poor communication and it definitely anticipated use certainly refers to all the time our users are spending trying to learn our systems. So what then are the characteristics of good UX? Lots of definitions, lots of explanations out there. This is my current favorite and it's from Kathy Sierra who used to run a user experience blog. It was called Creating Passionate Users and she doesn't create content anymore but the entire blog is still up there and it's really good if it's worth a look. So this particular graphic is often shown as a pyramid and it was based, she based it on Maslow's psychological hierarchy of human needs, right? And you read it that same way. The foundational stuff is down at the bottom. That's the stuff you've gotta hit and everything above that bottom bar is a refinement and it's harder and harder to hit, okay? So the way you read this, you start at the bottom and the first thing and the primary thing that users need their software to do is to be functional. There's something they need it to do and the software just has to do it. It's that simple, right? The next layer is correctness, right? It has to meet the functional layer and it also has to do it without bugs and it has to do it without errors, okay? Next layer is learnability. We've talked about that just a little bit, right? It needs to either be fairly intuitive or you've gotta give your users tools, right? So I'm not gonna go through this whole pyramid this way. I just wanted you to see how it reads but I want everybody to agree we've been doing this a long time and what we want is passionate users. We want software that creates flow and enchantment and it's kinda tough to get there, right? So what I'm gonna tell you about today gets you to that last 10% that maybe you're not paying attention to. So let's go back and look at this another way and let's start over at the bottom and let's see everywhere you need to use communication skills and let's talk pretty explicitly about what those things are, right? So functionality again, that's right there at the bottom and in order for software to be functional, somebody has to gather requirements and they have to write really clear requirements documents or use case documents and proposals that outline what the software's gotta do, right? And if you're a one person team, you're taking off your developer hat and putting on your communicator hat and you're talking to the state players. If you're a project manager, you're gonna put your best communicator on this project, right? And this used to be really well understood in the days of waterfall development. It was so important and was so foundational to the way that software was created that the team would give the requirements to the tech writers who would go away and write a user guide which would then be handed to the engineers, the developers, who would reverse engineer the software so that it worked the way the user guide said it was gonna work. And that way, on launch day, you had both a product and a user guide delivered at the same time, right? So that is the one thing I miss from waterfall development because it really understood how important communication was to this process. So at the next level, correctness, the developers who are developing need to take in those requirements, they need to apply them, they need to comment their schema very, very well and they need to be able to write testability, user testing help guides so that the users can test the stuff, give proper feedback, and the bugs get squashed before release. Oh yeah, I'm supposed to be giving you a little check marks to show you about this. So for learnability, we've already talked about those tools. It could be tool tips, it could be user guides, it could be training classes. I'll show you how I use annotated screenshots to sneak in user guides where they're not spec'd and there's no budget for them. An efficient system tells a story. In a way, it's really the digital version of some analog business process, right? And to be efficient, data has to be well organized, it's got to be presented in an organized fashion and all the steps the users have to take in order to interact with it have to be presented at the right time and in the right order. Usability means that the system matches the user's mental model, or if for some reason you had to adapt the mental model, it was done with the users in mind, hopefully with their input so that it makes sense to them. The business rules have been taken in and applied in a way that makes sense. Intuitive systems are created when the developers and the project managers understand human psychology, they understand how human beings interact with software and perceive data and perceive meaning and they advocate for the users during the planning process and all the way through the development. And then if you get to flow in enchantment, it's because you synthesized all of these communication skills all the way throughout the process. So these are the soft skills that tech communicators use every day and you guys are already doing this stuff, but I'm pretty sure that you just think of it as something you do as a developer. You don't think of it as communication skills. And I think it's important to remember that communication skills is not just grammar, right? That's foundational, but it's not just grammar. If you think of it that way, that's a very, very reductive view of what it is that you're doing. You know, it wasn't that long ago that FileMaker developers didn't dare to call themselves designers, but now I'm really excited to see that there are people who specialize in design and they say that's what they do and I would love it if in a few years from now we all dare to call ourselves good communicators because we've started to think about this. Maybe we'll even bring back the term technical writer. So there's another thing that I wanna talk to you about. It's a little bit metaphysical, maybe a little woo-woo, but I promise you it won't last more than a minute, okay? You guys know the story of the Chronicles of Narnia? Aslan creates Narnia by walking through the land and he's singing to his creation and as he comes to each plant he sings its name and as he comes to each hill he sings its name and all the animals and they all come alive when he sings their name. And I think about this sometimes when I'm creating a database at the very beginning and the reason I do that is because sometimes that's a, it's a repetitive task, right? You've got an ER diagram and all you're doing is opening a database and naming some tables and naming some fields, but I think that's a really important task. Selecting good names is really important and it's a way in which we're really capital A authors of the databases that we create. Think about it, to start a database we actually have to give it a name and click create a bunch of times, right? And there's a way in which we don't want to think about this very much. Naming conventions kind of sprung from the fact that we actually don't want to think about this. We want to all understand how we name things and we want to not have to reinvent that wheel every time we create a new database. But even if we use good, solid, agreed upon naming conventions it gets pretty hard to find good names for things in a very complicated database. The way you name things is really fundamental to data modeling and it's one of the ways that I've seen data modeling taught to people who don't have a technical background. You take the tools of grammar and you tell people to write a list of problem statements we call them or just simple sentences that describe everything that the database needs to do. And then you go through the list and you look for all of the nouns and you put those in a separate list and then you examine those nouns to see if you have to store data about them. And if you do then that's probably a candidate for a table. And this same technique is really useful when you're creating your use cases. This time you go through the list and you look for verbs and that tells you what actions the users have to take. So in every case, whatever message you're sending whether it's a proposal or requirements document, maybe you need somebody to clarify a feature request or tell them it's time to test a feature or maybe you're throwing up a dialog box, a show custom dialog because you're validating a process while the user's running it and they need to give you more information so you can finish the script or maybe you're just finishing a process and you need to tell the user that you're done. In any case, you're sending a message, you're handing over information and what you're saying needs to have a huge overlap with what the user needs to know. So the way that you do this is you subject every bit of communication whether it's a dialog box or a proposal to three primary tests. So the first thing is it's gotta be grammatical and that refers to that functional level on the pyramid. Everything else is on top of that. So if it's grammatical, it's gonna be functional but it also needs to be clear and I'm gonna talk about a lot of ways we can apply that concept. And the third thing is that it needs to carry the lightest possible mental load, right? So let's talk about human perception and let's talk about what mental load is. So mental load is the cumulative effort it takes to get through a task. The cumulative part of that refers to the fact that we have a working memory and it's a lot smaller than most people think it is. We can only hold a few things in our working memory at one time. So if we're guiding a user through a lengthy process that has a lot of steps, the first things that they've done and the information that they carry into the beginning of that task get dumped as they go through the process, right? And one of the most common ways that we deal with this, there are lots of design patterns for dealing with this but an easy one is breadcrumbs on a website. Even navigation bars in our applications in a sense deal with this concept of mental load. So if a user's performing a task, they get a lot of steps to do, they don't have to remember at the end how to go someplace else because they've got breadcrumbs to get them back where they were or they've got a navigation bar that's gonna let them finish and go wherever they need to go, right? So that's the first part of mental load theory. It's cumulative. The second part is that different tasks have different mental loads, right? So those mental loads are here on this slide and the first one is pre-attentive processing and those are primarily visual tasks. A great example of that is reading a bar chart. So the brain is hardwired to see differences and it can, your brain, anybody's brain can pick out the longest bar on a graph in milliseconds before you have to pay attention to it, okay? Attentive processing comes into play if the user's now figured out that the green bar's the long one and they now wanna know what that represents. They have to pay attention, they have to go down to the logo, the legend and read it and figure out what it means, right? So attentive processing means the brain is actively engaged in trying to get meaning, okay? And cognitive and mental load means that it's tough stuff to do, right? Reading is never pre-attentive because it always carries meaning and the user's always having to pay attention to it. But what you should know is that in literate societies, at least, anytime the human brain is presented with words, the brain wants to read those words. The brain is trying to figure out what they mean but the user's trying to do some work and the user's trying to ignore those words. So internally there's this struggle between do I read this or do I not read this? And there's another common design pattern we use to overcome this. I think you guys may have heard of this. I mean, anytime you throw up a dialogue box that has a potentially destructive action, you know this, you don't put the default button, you don't put the destructive, the okay button in the default position, right? Because the user's gonna not read the dialogue box, they're gonna reflexively hit okay, they're gonna do the thing, we're trying to let them have a chance to back out of, right, so you always put that button in the other position. Second though, make sure now that you're aware of that tension in your user's brains, make sure that every time you present words you've crafted them so that they've got a light mental load. So I'm gonna show you what this feels like. I want you to be in the user's shoes, I want you to have some empathy and I want you to more than just sort of abstractly understand what this feels like, okay? So these next tasks are really, really simple. There's gonna be some arrays and you're gonna find the thing that's different, right? And I want you to be meta about this, feel what your brain is doing as you do these tasks and I promise you, super easy, right? So to make this work, we have to clear the screen first, okay, everybody ready? Okay, everybody got it? Did that happen in a nanosecond? Did anybody have to pay attention to that? Here's a little hint, right? So that's pre-attentive, but we can make pre-attentive processing even easier, right? In that last example, we just changed one thing. We had a bunch of blue circles and one blue square, right? We can change two things and we can make that super pre-attentive, right? So not only is that easy to find, but now you can't look away from it, right? You know why you can't? Because your brain is trying to figure out why is that thing green? Do I need to do something about it? Is it telling me something? It isn't, but remember, think about what your brain is doing. It's like, it's looking, it's looking, okay? So that's pre-attentive. So the next task is gonna be attentive processing and this is literally the same thing. The only difference is that we're using symbols now and the reason this is attentive is because symbols carry meaning and your brain is now gonna be divided between looking for shape and do these numbers mean anything, right? Ready? Raise your hand when you got it. Okay, good. But was it easy? Say? A little bit harder. A little bit harder, right? It's not too bad, but it's a little bit harder and if you're trying to do something and you've gotta pay attention, guess what happened to your working memory, right? Something dropped out. Now again, I intentionally made two symbols that are very, very close in shape to make it as hard as possible. If we had done, if I had done threes and sevens, you would have found it really easily or fours and eights, right? But in the same way that we made it easier before, if we want to, we can make this easier by changing two things, right? So we can get it closer. It's still attentive processing, but we can reduce the level of complexity of this task, right? Okay, I'm gonna show you mental load now. Okay, you ready for this? I'm gonna have you read two sentences and I want you to really take the meaning on board, right? And as you're taking the meaning on board, think about whether it's hard or not and think about the empathy part of this is what happens to your users when you present information to them, okay? Okay, this is mental load and this is two sentences from a recent scientific paper. Raise your hand when you get it, okay? Couple hands, we have some scientists in the audience. Okay, I'm not trying to shame anybody. What I want you to know, what I want you to tell me, was that hard? Was that kind of rough, right? You really have to pay attention and we're technical people here, right? We're used to this stuff, but that was difficult. I chose that on purpose because I had to struggle with that. I was like, what in the world? Okay, this is, you might have heard about it a couple months ago. A couple scientists did an analysis of hundreds of recording of Freddie Mercury's voice. They wanted to find out why he was so awesome with imperative evidence, okay? So what happened? Why was that so hard? Okay, it was wordy, 53 words and there were big words and there were scientific words. They were words that most of us are probably not used to, right? And the construction of the sentences were complex. It was kind of hard to wade through that stuff, right? And there was a lot of jargon, a lot of scientific terms that most of us don't read every day. And there was a lot of data points, information that I frankly have no idea what that data point, what those mean, right? There's no, without help, there's no way I would know what that means. And so I'm not saying to you that this passage was inappropriate for its audience. What I'm saying to you is that this is a really good example of the task you have to do every time you communicate. You are the possessors and the owners and the creators of technical information and you need to translate that to layman talk every time you give your users a message. Proposals, dialogue boxes, whatever. You are the translators and the mediators of technical information for layman, okay? So you have to figure out what's necessary and what's not, right? So I rewrote this passage for you and I took it from 53 words down to 13 and I simplified the language and I took out all of the data except the meaning, okay? Easier? And this is kind of awesome, right? I'm gonna get off track for just one second. It would have been natural for him to sing as a baritone and yet he sang as a tenor because that's what rock and roll needs. That's pretty cool, that is pretty awesome. So this is the kind of thing I wanna teach you how to do. Ah, and this slide, I meant to set it up for you. It is from a blog post called Misbegotten UX and it was called an irreverence UX dictionary. So what it refers to is the fact that you guys need to take on the cognitive load on behalf of your users. It is your job to take on the mental load. It's your job to do the heavy lifting and give them the easy stuff. Make sense? Okay, so here's how we're gonna do this. These are the characteristics of good communications, good technical communications. Okay, first of all, they need to be brief. So as E.B. White said, he wrote the famous Elements of Style, omit needless words. So I took 40 words out of that sentence. Spare is not the same as brief, but it's related. Yeah, use it in the sense of having no excess fat, right? Don't give detail unless it's really pertinent to what the user needs. You're gonna have a lot of information. The user doesn't need to know. Don't burden them with it. Unambiguous is super important, and in a way it's really intention with this concept of spareness. Don't leave out detail that they do need, so you're curating the message all of the time. Your messages need to be consistent, and this has two parts. Consistency means that all of your communications should be consistent with themselves. So for instance, if you're referring to dialogue boxes, always use the term dialogue box. Don't say dialogue box sometimes and window other time, because beginners especially try to figure out if there's meaning. Is there some slight difference that I don't understand between a dialogue box and a window? And they're gonna blame themselves for not knowing why you used window one time and dialogue box another. So if you're consistent, you take that away from them. Now I know sometimes why we're not consistent in technical writing, and that's because our 10th grade English teacher said jazz up your writing. Technical writing does not need to be jazzy. It needs to be brief and it needs to be clean and it needs to be super consistent. The good news is it's formula, it's just formula. The second part of, let's go into jargon. So to be jargon-free, what I mean here is don't use file maker jargon, don't use database jargon, that kind of stuff, even if your users are technically competent. The biggest mistake technical communicators make is to overestimate the technical competency of their audience. I mean, our users and our project, the people on our development team give us great feedback and they understand what we're talking about, but they don't understand it the way that we do. And so the fact that they're nodding and using terms doesn't mean that they're as technically competent as we are. So stay away from our jargon, right? What you should do though is use their jargon and you should use it from the first demo. In fact, you should use it well before that. You should use it in the proposal and you should use it in your speaking conversations with them because your deliverables and your conversation with them needs to reflect them and their needs back to them from the very beginning. And I'm an independent developer and I'll be honest with you, this is one of the hardest things, hardest parts of my job. I don't know how it happened, but I have five or six different art departments that I do databases for and no two of them use the same terms. So although what they all basically do is job tracking and I could apply the naming schema of a standard job tracking model to the schema in my databases for them, I never do that. I use their jargon in the schema and it does two things. First of all, all of my databases have DBAs and it lets them know, it lets them be familiar with their databases as soon as they see it. And then the user facing label should use that jargon every time that they can. But it also helps me, right? Because if I use the term job with banner, who call it a job, and if I use the term campaign with client that I haven't signed a contract with yet, and if I use the term request from the other one, then every time I'm in that database and mucking around, it's reinforcing from me how I need to talk to them, right? So jargon free means us, our jargon, right? Short means it's not the same as brief, but it's related, use your five cent words, save your $5 words for your scientific papers. And simple refers to that fact, the thing that I just said about not overestimating the technical competency of your audience. Even if they are highly technically competent, they're busy, and if you make everything as simple as possible, you're not shoving stuff out the other end of their working memory. You are respecting their time and you're making an efficient system. And finally, make sure that everything that you communicate is well organized, and that means it needs to be organized within itself. So for instance, if you're describing a process, make sure that the steps are in the proper order and you haven't left anything out. And secondly, if you're doing any long form publishing, start with an outline or a template. So if you're doing, I have templates for my proposals and my requirements documents. And if you're doing a user guide, if you're lucky enough to get one of those, make sure that you start with an outline. So I wanna tell you a brief story. A few years ago, right after we got on TimerScripts, I was doing the first deliverable of a database. And I had, I thought it was so cool because I had figured out a way to put a message on a layout without the user having to click okay. I was giving them information and I was doing it without a custom dialog box and the user didn't even have to click okay. I would beep to get their attention, the message would flash up and then it just goes away. It magically clears itself and I thought that was awesome. And so I'm demonstrating this and my client who's asked me not to name her, Joke pounded on her desk and she said, stop wasting my time. And I'm like, what? And she says to me, there's too many words. You're wasting my time. And I was really kind of hurt and also frustrated, right? She couldn't notice the totally cool thing that I did because I was given her too much information. I really was wasting her time. So what was I doing? What did I do that was too many words? Back in the old days when I did a lot of training, I used to train a lot of developers and we had a bunch of classes called think like a developer, right? And this was the gold standard formula then of any message that we gave to a user when we'd done some kind of validation of a process and the validation failed and we halted the process, right? So the formula goes like this. We tell them what went wrong. You tried to send an email, we couldn't send it. We did something really cool and dynamic and we make sure that we tell them we know what record they're dealing with. So here Sir Speedy is calculated into the message so that we can remind them what vendor they're trying to email. And then we tell them what's wrong. The email address is missing, right? And then we tell them what to do to fix it. We say please enter the address and try again. And there's a variation on this gold standard. We're really helpful as developers and we wanna do a lot of hand-holding and what sometimes we do is we don't ask them to enter the email address. We take them to Sir Speedy's record and then we put the insertion point in the email address and tell them to put it in, right? That's a lot of hand-holding and that's a lot of mental load, right? I did not believe this in this meeting, right? This was grammatical. It was all the information that I thought she needed. And it took me a long time to agree. But here's the process that we went through to kinda clean this up, right? So the first one was okay, you're right. It's a little, the first one's a little awkward and we're gonna mediate this. I thought we needed to say the email couldn't be sent but when I thought about it, I thought, you know, the message is beeping, she's got an audio cue that something went wrong and she's hearing the beep and not the whoosh. So she knows the email didn't go out so we don't have to say that. And we can still be all dynamic and say Sir Speedy's email is the one that's missing and now we tell her what to do to fix it. And she said, I know how to fix it. That was my compromise. The first one was my compromise. The second one was what she wanted. Just tell me what's wrong. I will fix it or I won't. Let me have the agency to do that, right? Okay, so my thinking since then has been all about this second version. It's like it's primarily what I do now. I just tell you what's wrong and if I feel like giving you some dynamic information, you know, actually I'll come back on that just a second. The last version of this, which I call super brevity, and when I use it, I don't even put a period there. The reason there's a period there is because these effectively are bullet points on a slide and we all know that if you have one period on one bullet you have a period on every bullet, so. But the reason I do this email missing, it's not even a complete sentence and I don't put the period on the layout when I do this form and the reason I did this form is because the very first mobile layout I had to design was for some electricians out in the field and it was a long process. It was like eight or 10 screens and we were doing this merge field on a layout and they had iPhone 3s and they wanted to hold them in portrait mode. So I could maybe get two words on there, three if they were super short. So now I use the super brevity a lot on the desktop even though I've got Bukku real estate. So what I'm gonna say to you is that no one form of brevity here is the right one. They're all correct in different usages and the art to what you need to do is to figure out which one is important. So how do you decide? You make something fail at the first delivery meeting and you show a typical message and then you tell the user, I can give you this much information. Is this what you want or I can give you less and you write there in the dialog box in the script you fix it and you show it to them and let them decide and they may decide the middle's good or no and what they most frequently do is they say something like, well we here in the art department know what we're doing just do the super brief thing but the managers say need a little more help they're hardly ever in the database and give them the other one, right? So the point is you put this task of how much hand holding to give to your users right on the desk in the first demo and you do it until you really understand what they need and you let the clients figure that out, okay? So I'm gonna show you how to do this thing that I've been talking about, right? Here's what it looks like. This is just a demo file. I said there's no programming required and there isn't, there's a demo file with these two scripts in it and you can plug them right into your databases and they're gonna work and here's what I mean. So pretend that I've done some long script and something failed so I'm just gonna click the button. There's the email's missing and it goes away, okay? And this is what we call reduced interaction cost, right? We have to give the user information. We don't need anything back from them. We've beat to get their attention. No, I'd never make it that big on a real layout but I wanted to make sure it read in the back of the room. But when we do this, we put that, it's a merge field on a layout. Is everybody pretty sure how I did this? Do you want me to explain it or not? Yes, all right. So, luckily, I have a couple of slides that explain, these are two scripts and one sets the message in the merge variable. Everybody know what a merge variable is? Who would like me to tell you what a merge variable is? Awesome, okay. So you put a merge variable on a layout and when you're doing the design, you know you're gonna do this and you put it in the same place on every layout and you put it up there and you make it read because it's only gonna show when it's got data in it and you beep because remember, there's not gonna be a dialog box, nothing modal is gonna happen. The user is not gonna be stopped doing whatever they're doing. You're stopping the script in the background but the user can keep going. So you beep to get their attention and then you set the message that you need to send into the parameter of the set message script. You install an on timer script that's the clear message on timer script and then you refresh the object so that the message shows, right? So that's all there is to this message and then the clear message just clears the variable, refreshes the merge field so that the message goes away and it installs the on timer script. And the reason it does that, I'm not sure if you know how these work but as soon as they run in the window, you invoke them in and they run until you stop them somehow and so installing an empty on timer script clears it so that it only runs once, okay? And that's in the demo file and it is up on my website, the session website. So this is a real legacy dialogue box that I encountered not very long ago and it is not spare and it is not brief and it is not consistent and it is not very legible and it's not safe, right? So the first thing is the default button is the okay action, right? And there's some jargon in there, cut and copy. Absolutely cut and copy is basic, basic stuff, right? But it's still jargon, right? Okay and if you don't do any programming, the big dialogue box on the, is that the left side? Thank you. Is the script step and the little dialogue box on the other side is what the user sees, okay? So let's fix this thing, okay? This is, and again this is an iterative process. I'm gonna show you a couple of examples. Medium spare, the title bar of the dialogue box says verify move. So instead of cut and copy, I tried to match the language a little bit better and make it a little more consistent within itself. Oh and let me tell you what this does. It took me a while to figure it out. What it did was it took some contact information from one part of the database and it removed it, it cut it and it pasted it someplace else, right? So it is potentially destructive and some of it was cut and copied and some of it was copied and pasted, right? And I didn't think it was important that some of it was moved and some of it was removed. That part doesn't matter. The important part is that some of it is cut and isn't gonna be there anymore. So the first thing I did was remove that part. And I fixed the dialogue box, so the order of the button so that it would be safe and already it's got a little bit lighter load. This was all the further the client wanted to go. Here's how I would have fixed it if I'd been given my absolute druthers, right? So I made it even more consistent. So the title bar says verify move. I'm only using the word move in the message of the dialogue. I've removed all the explanation about every individual little field that's gonna be cut and copied. I don't think that matters. And then part of the reason this dialogue box was so dang wordy is this artificial construction in this assumption that every button has to say okay or cancel. And if you think your button has to say okay, then you're stuck writing this question that can be answered with okay, right? So if the button reflects the verb in the action elsewhere in the dialogue box, you don't have to do that monkeying around with an artificial wordy sentence, right? And this is much lighter, much easier to get through and much safer. Where are we on time? 436, oh, we got time, good. Okay, so short words are better. And this is what I said about your 5 cent words versus your $5 words. And I just went through, oh, maybe I shouldn't say this. I'm gonna say this. I went through some postings on the FileMaker community tech talk. And I pulled out some big words that I don't think people ought to be using even amongst ourselves, right? Because they just carry mental load and they're not as clear. We use them because they make us sound smart, but we are smart, so we don't need to sound smart. I always like use instead of utilize, feature instead of functionality. And I won't read all this, but I wanna talk about that bottom one. And that bottom one is there because I gave this presentation to FMDisk a few months ago and we had this conversation about the bottom pair, right? Somebody said, I do blog posts and I don't talk to my users that much. I talk to other developers. And I like this word instantiate. Well, I like it too. It has a specific meaning, right? But I would say that it has no meaning in the FileMaker world, no meaning. Now it has real technical meaning. Let me explain that to you. The technical meaning, if you don't know, is that whenever you declare a variable, you give it a name and you put a value in it initially in a script. So the first time you use it within a script, that's called instantiation. Does everybody feel smarter? If you're writing for beginners, the beginners are gonna be scrolling through the script steps looking for instantiate variable. There is no instantiate variable script step and for that reason I say it has no meaning in the FileMaker world. Now we can argue about that in the hall later, but I would say that even if you think your audience is us, you're forgetting about the people who need to solve a problem, who aren't us yet, and who wanna read your post, and who have searched the internet for the great information that you have, and under the gun, they've got to figure out how to do something really hard that you know how to do really well, and if you use simple words even amongst us, you're gonna pull those people up with them. And I would also say that it elevates your material above functionality and correctness up to intuitiveness and efficiency. So if you care about user experience even amongst ourselves, I would say that you should stick to short words. So let's talk about writing instructions. Now everything that I'm talking about has to do with whatever you're writing, but I'm using the user-facing stuff because hopefully it's what we're doing most of. So this is a typical construction of the first three steps in a tutorial that might teach somebody how to create a new user account in the security model in FileMaker, right? And I see this kind of stuff frequently. So let's go through this and let's figure out how to clean it up. So step number one is not well-organized. It's perfectly correct, but it's not well-organized. The original said, choose managed security from the File menu. Well, the user has to find the File menu before they can find the Manage command, right? And again, this is something that all of us kind of know. We hear that, we all say this. When we talk, we say choose this command from the X menu, right? But if you adjust your thinking a little bit and talk about the menu first, then again, we're pulling those beginners along with us and we're making the load lighter for anybody who does this once a year when new employees come on and they just need to read your tutorial to figure out how to do it, right? So step two, step two, the original was enter your credentials and click okay. Now, it is consistent with the interface thanks to a recent change in this dialog box where it says enter credentials in the title bar. So it is consistent, but I still say it's wrong and the reason that I say that it's wrong and unclear is because even though we would all love to think that every user is hanging on our every word and reading everything, we already know they don't, right? They're reading inattentively, they're trying to ignore everything that they can ignore and what eye tracking studies tell us is that instead of starting at the top and reading down, what they do is look for places to interact with dialog boxes. So what they're gonna do is they're gonna look at the two fields, they're gonna look for things like pop-down menus and they're gonna look for things like options to click and buttons to click and they're gonna look at that and if they can't figure it out from that, then they might read the text, right? So the better way to handle this is since they're gonna be looking at the fields and trying to figure out what to do with the fields as you refer to the field names and notice something else I did here about consistency. As a writer, I am somewhat troubled by the capital A account lowercase name. I take a deep breath and I go on and I put it that way in the instructions because again, we just don't want users trying to figure out if there's meaning, why did I do that? I just want it to be consistent, okay? And I made one other change to this. This is an example of making something longer to make it more clear, right? The original instruction said enter credentials and click okay. This is a two part kind of a sub routine step, two things are put together in one step and we all know that you do one thing and then you do another. But beginners don't do that and it's surprising how many times they try to figure out how to do something at the same time, right? So I like to emphasize that you should do this thing and then you should do the next thing. So I put the word then. Anytime I do an and construction because I'm stringing two tasks in one step, I'd say and then. And then finally, the old one, the old instruction was click the new button. And this is another example of making something, no, this is, I made this one shorter. From click the new button, I changed it to click new. And I drew, I wanted to draw your attention to this because I think I hear people most of the time, we're really comfortable with saying click okay. But for some reason, every other button, we need to call it the new button, the create button, the save button, right? And I'm just saying that's too many words. Let's simplify it. Let's just say click new and make sure that we give our buttons really sensible, easy to understand names. Okay, so what we've done in these first few slides is we've made our instructions really safe for beginners as far as what they're supposed to do is concerned. We are telling them what to do, but beginners don't know what's supposed to happen when they do what they're supposed to do. So we need to add something to that so that they can verify each step of the way that they're, or they can validate that what they did was correct. So you need to add to every action instruction a separate results instruction. And you need to do it all of the time so that your citizen developers or your, anybody who's beginning can understand, can verify each step of the way and they don't get to the end of the process and something went wrong and they don't know what went wrong. They don't know where they veered off. Now we've introduced a big problem though. This is a lot of text, it's a lot more words and it's getting wordy and it's gonna annoy the technically savvy people, right? There's a lot of stuff they don't wanna see. So we fixed this with formatting. We just dropped the results to the next line and we can even make it italics if we don't hate it and we can make it really, really clear that this is slightly different than the action. So we have an action, we have a result for every step and we've made it really easy for the technical folks to skim and we've made it really clear for the beginning people. So what we're doing here is we're writing for a broad audience and we're making it as easy as possible for everybody. Make sense? Okay, this is what I promised to tell you about how I sneak in user guides. So using the rules that we just talked about with instructions, oh and by the way I meant to tell you why I'm really focusing on writing instructions. Even if there are no user guides specced in your projects, how do you know you're getting good testing if you're not writing instructions for your test group? Can you be sure? Here's what happens to me all the time. My users are super busy and I'll give them a checklist that says check all this and tell me if it's good and if it's not good, tell me why it's not good. And so I will have done this beautiful demo and they will have given me this amazing feedback and everything will be great and they have two weeks to give me feedback and the day before the feedback they call me and they go, I'm trying to run that report and I thought it was on the layout on the thing with the what's it and they don't remember and I'm lucky if I get the call. Most of the time what happens is they give me a partially completed checklist back and we're all spinning our wheels. So what I realized was that I got much better compliance. I got much better feedback. If in addition to a checklist of everything they need to check in a delivery cycle I give them some instructions. So I write these formulas like I just showed you and sometimes I also do annotated screenshots. Now sometimes if my users are technically savvy I just do the screenshots. So sometimes it'll just be here's the button you click on and if there's an interesting dialogue box that they have to deal with that I think that might trip them up I do an annotation like this and I know it works for two reasons. First of all I get really good compliance now. I get much better feedback on cycles and that means that we're releasing better software, right? But secondly I walked into one of my users' offices one day and she had these pinned up, these ugly little things pinned up all in her cubicle and I was like oh man you print those out huh and she goes yeah I'm gonna put them in a book and they're gonna be the user guide. I was like cool I'll do more of this. So this is just, I just use Sketch but there are a lot of screenshot annotators and the important thing is that I'm really explicit with it. Click here, pointing arrows the whole thing. And it's not attractive but it gets the job done. Okay so this is an iterative process in the same way that you plan a database before you execute it if you're gonna write something you need to plan it and even if you're just writing your testing guide even if you're just saying here are all the things I need you to check, run through the process to remind yourself if you're gonna write instructions run through it so that you give complete instructions because if you don't they're gonna think they screwed it up and they're gonna report a bug that doesn't exist, right? So run through the process, write it and then revise it. And the revision's super important. I've been writing professionally for a long time. My first drafts are never good. They're better than they used to be but they're never good. The good happens in the revision. The good happens in the editing and editing is way harder. It's way harder than writing. Did you agree? Yes, thank you. Way harder. Okay but it's a cycle. Plan, write, revise. So how do you know if it's working? I've told you some of the things, right? You're getting better compliance, you're getting better feedback. Oh no, I jumped in, sorry. How do you improve? How do you get better if you don't think you're good at this? Well it's just like we used to say about skiing. It's time on boards, right? To write better, you gotta write more. Whatever it is you're doing. They've sort of debunked the 10,000 hour thing is not quite true but you still have to practice, right? So write more. Ask for more writing tasks. Deliver more writing even if it's not spec'd. Ask your project manager to put you on writing projects. And then ask for mentoring for that. Lots of good courses out there. If you're near a university, they still teach technical communication. There are some good online courses that you can also take. And make sure that you get feedback explicitly about your written material. Some of this is gonna be contextual. Like if you send out a proposal and you get lots of questions about it you probably didn't do a great job, right? And the feedback that you get will help you do better next time. But do team review. Team coding works really well and it works really well because two sets of eyes are always better than one and it can kinda shorten the cycles of writing. So do team review on your writing. Explicitly ask your users if they understand the messages that you're giving them. So not only do you do that at deliverables with your demos but explicitly ask them, is this helpful? What would be more helpful? And even if it hurts your little grammarians' heart kind of grin and bear it and write what they want you to write you can push back a little bit but do what they want. And finally you can hire professionals. There are professional writers who will either do training for you or do your writing. Maybe you're in a vertical market and you're doing, you know, you're... Oh my God, I almost said core competency. Your strength is not writing. You could, I scared myself. You can hire a professional to do your writing or you can have somebody do a tech edit on it for you or you can have somebody do some sort of team coaching for you, that kinda thing. So just two more slides. Good technical communications. This is kind of what I've been saying all along. If your users are making the right choice more often and if they're doing it more efficiently, if that's going up, you're doing a better job. If the requests for clarifications are going down, if there's less negotiating about what the message means that's obviously better and tech support calls go down when you have better support documentation for your systems. And finally, at the core, remember the bottom line, the functionality, the bottom line of any message that you send is that you need the user to take some sort of action or make a choice. You gotta get information that helps them do that and your job is to sort of curate the message so that they are able to take the right action. Okay, so let's see. The session is not gonna have any updates even though it says it will. I uploaded this stuff on Friday and it hasn't changed since then. And there's some housekeeping. You guys have probably all heard this 100 times already. Somebody wanted to tell me the housekeeping about the evaluations? Yes, the evaluations. If you did more than one evaluation before yesterday at 5.30, only your last one was saved, please redo your earlier ones. You may have already done so and I think that's it. So we have, I think we have time for questions. Yes, we do. Does anyone have any questions? Comments, rude remarks, stories about doping and bicycling. Yes, yeah, so you do that programmatically. So the question was we've got a variety of people that we wanna serve with a single dialogue box. So you do that in your script. You set a conditional variable and all you do is an if statement. You gotta figure out how those people are divided. Maybe it's by privilege set. Maybe it's by where they came from. I don't know, you figure that out. And then you do a bunch of if tests and what you do, I don't know if you've seen this, but instead of hard coding the dialogue box, you set the message in a variable and then you put the variable in the dialogue box and then all you, so you see where I'm going, right? You just do an if statement. You conditionally set the variable and then you show the right variable in the dialogue box. Does that make sense? Yes. Oh, they didn't. Okay, thank you. I did think I followed the instructions. I will ask Mark what happened. I have a question about in terms of mental load. Yeah. Sometimes I have to decide between a text button or a glyph button or a glyph and text button. And I was wondering if you had any rules or thoughts on those? You know, I'm a fan of text buttons. I'm a writer, so I'm fully willing to admit that I'm biased on that. I think that the problem with that, and one of the reasons I think that is that the symbols aren't often as evocative as we want them to be and maybe they're not as well-chosen, but if you have really well-chosen symbols, they do convey meaning really well. One thing that I've seen done is that when you initially launch a system, you use both text and buttons and then over time you switch. You know, that's a lot of extra work, but that's what our jobs are about, right? Is that we continually, she said something that I love the other day, design is a continual process of removing complexity, right? So that's a perfect candidate, right? Maybe the system goes out for a little while with both, and then as people get more used to it, you can reduce it to the symbol. Okay, thank you. Yeah, you're welcome. Yes, I'm sorry, could you go to the microphone? I'm sorry. Just following up on that, it'd be a better option to give the user the option to say, I'd rather have buttons or I'd rather have... So you could, you know, you could set preferences, right, and I don't know if you've ever seen this technique, but you have a user preferences file, and with hidden objects, we can do that, right? You could have two button bars, one with buttons. You could have a third one with both buttons and more, and so maybe that's another way to deal with it, right? And you just conditionally hide, show the one that matches the privilege set or department or whatever of the user. Maybe that works. That's more initial work, but yeah, that would work. I would do that. Yes. Much of what you mentioned is consistent with Microsoft Manual style. Oh, okay. Do you recommend a standard? Okay. Okay, I didn't know that. Well, in addition to the individual examples, do you recommend a standard, a written standard? Oh, for sure, yeah. The question is what standard, right? You know, so I was trained with the Chicago Manual style because I was writing newspaper articles, and then I switched to a Riley style guide, much of which is, it formed, definitely there should be a guide. And one of the things that, you know, I would love to do in a big writing project is actually create that manual and say, here's how we're all gonna write. It's different. The Chicago Manual of Style had very different needs than something that's written for technical communicators, but absolutely, just as you have naming conventions or, you know, all of that kind of stuff, for sure. Can I point you to one? No, mine's kinda in my head. The reason I'm asking is that particular one by Microsoft is specifically for software. Okay, yeah, that might be a really good starting point for people rather than rolling their own. Is it, if I Google Microsoft, what'd you call it? Microsoft? Manual of Style. Okay, excellent, thank you. Anybody else? Well, if you think of something later, feel free to waylay me in the hall. And thank you very much for coming.