 This talk is about the seven righteous fights that you should be having already. And it's about your inevitable failures, because I know about these things. I'm sorry to tell you you're going to fail on these things, but I'm here to tell you how to make it better. 20 years since I learned HTML in an English class, we did some HTML coding on a project on Arthurian legends. So that's where I'm coming from technology-wise. In the intervening time, I've been the lead tech writer on at least 10 new products. And I am a person who has been trained to see and analyze patterns and nuances in how projects work. And I'm going to tell you there are some common points of failure. We get stuck in a rut. This is a picture of a Central African highway. That's what it looks like when it's going well, because you get stuck in a rut. You drive trucks over mud, you get a rut. We all have ruts in our programming. We all have places that we get comfortable in how we work. Like, I am an early-stage person. I really like the start of a software project. I really like being in there. But that means that if you're only an early-stage person or only a mid-stage person, you don't understand the pain points of other stages of software development. You're one of those people who's like, I only work for the first two years of a product, and then I leave. You don't know what happens at year six when everything goes to hell. So who here has gotten the retirement lecture on compound interest? Yeah, right? Like, start saving now, or your retirement is going to suck. Compound interest is magic. Compound interest is also horrible, because it applies to technical debt. The more you make mistakes in the beginning, the more horrible it is to fix them later. So this is a story about a product that I was working on with a startup. We were doing this really cool thing, and we were scrambling to make it ready for a trade show. You all been in that position, you're like, got to get it ready, got to get it ready. And so we were stripping out everything that was unnecessary as fast as possible. And then we went to the trade show, and we got the proof-of-concept contract, and we were so excited. And then we realized it was for a company in Brazil, and one of the things we had stripped out was localization. So what we had to do was take all of the labels that we had hand-coded in English, and port them back into something that could be translated. It cost five days to fix it the wrong way, which is just to say, put Portuguese hard-coded labels in. It cost two weeks to fix it the right way, which is to say, put references to a list that you could translate in. I bet you have all, at some point in your career, hand-coded a label. Don't do it, because it's gonna cost you five days to fix it wrong, and two weeks to fix it right, and that's in the early stage of a product. As you get later and later into a product, it's gonna cost you months. It's like, oh, localization is so expensive. It's not that expensive if you do it at the beginning. You say to yourself, well, I don't need to do that right now. I'm just gonna get a minimum viable product out. But I'm telling you that leaving these things out to the last minute, or until after you get your first demo or prototype out, is like leaving yourself to shove chocolate chips into an already baked cookie. It's bad for the chocolate chips, and it's bad for the cookie. You don't want to be doing this. You want to have your cookies baked, or your chips baked in. So that's localization. Here are the things that I know you can do for localization. You can make all of your labels refer to lists, so it doesn't matter how you're doing this. You can avoid ever putting words in your images. Don't put them in your logo except for the company name, and don't rely on screen captures to be doing your work for you. Don't say, read this screen capture so that you know how to do our product, because it's gonna look different in another language. Build in support for extended characters. It is dehumanizing and extremely rude to tell people they cannot enter their name in the way that their name is. And I'm not saying their real name, I'm saying their actual name. Their actual name is really important to someone, even if it's something that you think is frivolous and full of emojis. The late Noreen Plunkett used to keep a list of all the ways that people would nangle her name, because she had some Celtic diacriticals in there, and nobody could handle it, like conference registrations, like webpages. There was just this huge list of ways that people had disrespected her core identity. It doesn't take that long to build in full character support. Security, okay, brace yourselves because you all know this could be a book, right? But let's talk about some easy wins. The internet is not actually a series of tubes connected by guys at ski masks, despite what we have been told in the television. It is complex and beautiful. And probably nobody's going to find you at first if you're a new product. But eventually there will come a day when you have to write a super embarrassing email because your Waffle Buddies app has been compromised and someone has put everyone's syrup preferences up in a paste bin for the world to see. Do you want to write that super embarrassing thing? No, you do not. Security is neither cheap nor easy, but it beats the alternative, which is fixing things in a hurry and expensively because it's gone wrong. You should hire somebody who knows about security so that you can make sure you've covered your basis. You don't have to hire them forever. You don't have to have an onboard security person, although it's probably a good idea, but you have to be thinking about how you can do this better. If there was one thing I could convince everyone to know in their heart, deep in their heart, if there was one thing I could convince everyone to know, it is that authentication is not authorization. Authorization is not security. Just because you can prove you know who somebody is doesn't mean that you're letting them in the right places. Just because you're letting them in the right places doesn't actually mean your data is secure. I wish that there was like a children's book on this, I'm serious, because we're just not teaching it. We're confounding these things all the time and it's horrifying. Leave room for encryption. You can use SSL internally already. There's no reason you can't be using that in your internal things and when you go to expand, that's gonna be easier. You should be using HTTPS for all of your pages, not just the front one. I know you've all seen websites like this, you're like, oh, HTTPS, why did you switch? Why is it suddenly insecure? I don't feel happy about that. If you bake that in from the beginning, if that's just the default for how you code something, you're gonna have a much easier time when you have 300 pages and you have to do a security audit, which is what I'm doing this week at work. Know what kind of data you are redacting and what kind of metadata is actually super revealing. We think that if you strip off the names and the social security numbers and the zip codes of something, that's fine. Did you know that HIPAA restricts you from doing birth dates of anyone who is older than 89 because it's so identifying what their exact age is? We're saying there is a lot of things that you can correlate and confound with each other and then people know more than they should know. So only collect the data that you actually need. How many of you are building something that actually needs to know somebody's gender? And yet how many of you are building something that has a gender box by default because that's what we're used to? I want you to stop and think about the data you're collecting and why does you actually need that? I want you, and this is my radical call to action, I want you to delete users. I want users to have a way to say, not just delete the access to my account, which is what we usually mean when we say delete, I want them to be able to wipe themselves out of the system because everywhere that we have left ourselves, we are vulnerable. There are some exceptions to this, there's some financial stuff, but I think that in seven years, your data should just sunset. It should just go away unless you have actively preserved it. We're building these chains around ourselves like the ghost of Barley in a Christmas Carol. We're dragging them through life. I am now almost 40 years old and there is evidence of me from the start of the internet from like 21 years ago being a college student and using Usenet, right? I don't necessarily want that dragging behind me forever. So I'm saying seven years, delete the data, tell everybody that's what you're gonna do. Say like Flickr, hey, we're gonna take this away unless you wanna keep it, you don't need to have that. And this part makes people really uncomfortable because they're like, well, we could store it forever. I don't want you to store it forever or else you're gonna end up like OPM. You're going to end up with files that are 20 years old and super vulnerable. This is Santa Claus. He has a naughty list and a nice list, right? So this is, you should be whitelisting the scripts that run on your web pages including the web ads. This is security by whitelisting because I'm really tired of injection attacks and ads that have nothing to do with the site but because they're just passing through the scripts that come with the ads, I'm getting hammered and this is why I wanna put on ad blockers. If you can say to somebody, hey, we've already verified the people who are providing the scripts here, we know that they're good guys. You can be a lot more aggressive about saying don't use an ad blocker on me. Don't recreate the wheel. There are people who believe that they can improve on something that already exists just because they're doing it new. If you are selling to enterprise or social networks, don't recreate Active Directory. Don't recreate OpenID. Don't recreate SAML. A whole bunch of really smart people have already solved this problem and the IT managers and flunkies that the company you are selling to would like to not have to put your funky weird homebrewed solution for authentication and authorization into their AD directory because it's not gonna work well. So don't recreate the wheel, just use something that already works. Stop saying that word. Do you know what word it is? Might be Humberning. It's not Humberning. It's secure because every time you say we're building a secure, rabid lawyers sit up and look around for their next victim. Nobody is secure secure. You're more secure. You're better secured. You're considered about security. But when you say secure, you are promising something and when you fail to fulfill, people are going to be super angry. So fight number three, extensibility. This is the ability of your software to play nice with others. You say to yourself, it's only internal APIs. I was just on a project where we did a whole bunch of internal APIs and they had the ugliest names ever. They were named after a dead product that never ended up getting released and they were like this long and they had typos in them. But it didn't matter because they were internal and we could all look this up anyway, right? Well, it turns out that some people don't want our pretty interface. Some people just wanted to use our APIs and then we either had to scramble and rename everything, including all of our internal stuff or we had to show them our really ugly API names. If we had done this right in the first place, we would not have had that scramble. I really like Legos as a metaphor for APIs. Legos have a universal interface that you can just plug things in too reliably and you know what's going to happen every time. I want your software to be like a little Lego stud. I want you to just be able to say, I'm going to be able to attach things to it and not worry about it. So documentation, I'm a technical writer. You knew I'd get here, right? Your documents have to be more useful than Stack Overflow. Nobody buys software because they saw an awesome PowerPoint about it. Like that's just not how it works. They get excited about software if there's an awesome PowerPoint. But then somebody says, hey, I need to know how that's going to go in installing in our environment, right? Your software is not a state secret. If you lock it behind something, you are depriving people of the ability to decide whether or not they really want something. I have this fight all the time and I lose it and I do not understand. Nobody is really going to go to the effort of reverse engineering your product because of your user documentation. It's like this bugaboo. They're like, but what if people saw our secrets and I'm like, they're not secrets, they're our business model. So how many of you bounce out when you try and go read documentation and there's a login page? I bounce out, I hate that. But if I could read a little bit of description about what it is that I'm going to be getting, there's something that motivates me, I might log in to read white papers, maybe. I don't like logging in. Like why should I sign up for spam from your company if I don't even know I want to buy that? Documentation is not state secrets. Documentation is subtle self-promotion. You're like, hey, here's everything you can do with our product, isn't that awesome? I'm going to give this information to you for free. I'm so super. So user documentation is actually pretty easy to retrofit. That's what I do, that's my job, I go in and I take companies that have neglected to do user documentation for the first two years of their product and I fix it in six months. It's easy. These are the things that are not easy. Do you have a tax on your senior developer that costs 10 hours a week and goes on for a month? Do you think you do? Because you do if you are onboarding new developers. If you are onboarding new developers, they must understand how your environment works and the only person who can explain it to them is the old developer. So you're saying, hey, I know we're trying to go really fast here but I need you to slow down and explain it to this other person and it gets really slow. So document your developer onboarding. Document your build process and procedure because it's really hard to do agile development and publishing if nobody but this one person knows how to do it and if they get sick or distracted or cranky, you can't build because nobody knows how to change the procedure at all. They're like, well, I click a button. Jenkins, hello. It's not there. So when you hire a build engineer, make them show you some writing samples. Secretive build engineers are bad build engineers. They are hoarding knowledge and they are putting you at risk for not being able to push your product out. Release notes. Nobody likes reading documentation but if there is one kind of documentation that actually gets read, it is the release notes because people who are installing really need to know if you're about to screw up their whole system or if you have actually fixed the bug that they filed six months ago and they would really like you to fix. So you have to do release notes. They don't have to be super charming or cheerful but they have to be effective, timely and complete. You want to document your coding intent. As a writer, I really like going to sprint planning meetings because it's pretty much the only time that somebody actually spends time explaining the business reason for the coding goal. Otherwise, we just have all of these little stories that I don't know why we're doing them and I personally work a lot better if I understand why it is we're doing something and what's going to make it more effective. Also, those are really ephemeral meetings and you may not all agree on what happened. So if you document your coding intent and what you're trying to accomplish, it's gonna work out a lot better for your organization. Affordance. Affordance is what your software makes obvious or easy, what your software is trying to get people to do. This is the crosswalk where I go to work. You may notice a little problem here. The crosswalk button and the crosswalk are not in the same place as the sidewalk. This is troubling right now in the fall because I have to go stand on the grass, it's not great for the grass, and it's pretty bad for wheelchair users or anybody who is on crutches. But imagine, I'm from Minneapolis, what it's going to be like when we plow the sidewalks and all the snow piles up against the post and we can't get to the crosswalk button. This is bad affordance, we don't want to do this with our software. Affordance is the big green okay button and the small gray more information button. It's how we're shaping people's reaction to our software. One of the things that we never think to do and it's an affordance thing is, when we run our software, we run it with all the privileges turned on. So you perform a task and it goes great, woo, it's good. Have you tried performing it without all of your elevated privileges? Have you logged out and logged in as an unprivileged user? How long does it take you to do that task? Do you want to live like that? Do you want to live like that where it's like super awkward and you have to go through a bunch of steps and confirm a bunch of things? I don't think you do and I don't think your users do either. Affordance is also used in some really interesting sort of nudge ways to improve our behavior. This one is about how sometimes banks will let you just take the change, the extra change to round up to a dollar and deposit it in a savings account. That's an affordance that allows people to do more saving without any particular effort on their end. We want to make software that creates good behavior with no particular effort on our user's part. This figure is called a homunculus and it's really distorted because it's about how the nerves map to the brain, how much sensation we get from different parts of our body as opposed to our visual perception of our body. I think that as developers, we sort of end up in this visual perception part of our body where we're like, this is how I believe the body works, this is how the software works, but we're not actually replicating the daily tasks of our users. So if it's like a minor irritation to us, it might be something that they have to do 14 times a day and it's more irritating every time. Here is the secret. You think that you're gonna go back and fix it. You think every time you build something cludgy and horrible, you're gonna go back and fix it. There's a sprint dedicated to resolving technical debt, right? Used to have these, it was really cute. That never happened. Here is the secret. You are never going to fix it later because by the time you get to later, even if you had time, your users have adapted to the broken way it works and they are angry that you want to change it. You're like, but it'll be better. And they're like, my whole workflow is centered around how it's broken. I do not want you to move my cheese. I am angry at the mere thought of you moving my cheese and making this any different than it used to be. You cannot fix it later and you cannot step in the same river twice. You only get one chance to be right the first time. Fight number six is acceptance. Find some people who use your software. I do not mean people who buy your software and I do not mean people who show up at trade conferences. I mean people who sit in a fire truck and use your navigation software to get to the right place. Actual users, find one of them, find five of them. It doesn't have to be statistically significant at this point. You just need to talk to them. You need to break out of your echo chamber because it is so easy for us to assume that people are living like us and it is so wrong that they are. I really believe that five users and a WebEx session is gonna change your world. Microsoft, they have this beautiful testing suite with the two-way mirrors and the recording devices and it's all very exciting and I was super excited to get to use it but it didn't teach me any more than just sitting in a room with the user and here's the important part, shut up. Don't tell the user how you expected it to work. Don't tell the user how to make it work. Sit down, shut up and take notes while they work through their task flow because the second you interfere, you have changed that state. Your physics is all broken. Really often, we hire user interface designers before we hire user experience designers because you have to build a piece of software and it has to have a front end of some kind. But if you don't get to hiring a UX designer eventually, you're gonna be in trouble. So if you can't win this fight, if you cannot talk someone into hiring you an expert and how people are, give up and become a student of UX. This is always going to make you a better developer. Nobody's going to say, oh, it's so terrible that you have sympathy for our users. That's not how it works. You're gonna be like, I have a badass programmer and here are my user studies. I think that's gonna be a great selling point for all of you. So you wanna say I'm a student of user experience even if you're not an expert. The place you should start by the way is Kathy Sierra's book, Badass, Making Users Awesome, which is stunning and wonderful and I literally carry a paper copy of it around because it's just so clear about how it could be better UX designers. Fight number seven, accessibility. Have you ever looked at your software with your glasses off? Can you still see all the elements? I turned 39 this year. I started needing reading glasses because suddenly the conference badges were too close to my face. I'm like, oh, I can't see that. I'm like, what is this? So I've never worn glasses. If I wanted to look at a user interface element, I would borrow my spouse's glasses. I would say, hey, load me your glasses so I can see what the screen looks like when your vision is a little weird. Have you ever looked at it on a non-retina screen? This is a real usability problem because we all get these beautiful MacBooks and they are gorgeous and then that's like the bad one and the big monitors that we're using to code. They're gorgeous, they're clear, they're glorious. That's really not how it works out there in the world. There are people using some really terrible monitors and you're not making your stuff accessible if you have to have really fine color gradations to see what's going on. Have you looked at it on an actual phone? Not a phone emulator on your retina screen but an actual phone and not your newest iPhone but like your dad's phone. Like the one he has all cranked up so he can see anything because he's blind as a bat. Have you looked at your stuff on that? Because even though the CSS claims it's gonna reflow, it doesn't always and even though the colors look great on your monitor, they don't always and if you're going to be accessible, you have to look at it in a different way. Did you know that 8% of men are color blind? Red, green color blind. Makes it really hard to tell what your interface elements are if you're doing stop lights for your logging. Like which one's gone wrong? I don't know, the brown one? Like for some reason, the 8% of men who are color blind pretty much never become user interface designers. I'm puzzled by this but it's true. The people who can see well are the people who end up in the arts who end up in user interface design. Don't do this to people who have screen readers. It's really easy to say, click here, click here for the link. If you spend an extra 30 seconds crafting your link, giving it a target and a name and a destination, you're not only making it possible for people using screen readers to see what's going on, you're making it more trustworthy for every user to be able to say, hey, I know where that link's going to go. I'm not about to get hijacked somehow. You know what? Not everybody has broadband and not everybody has their employer subsidizing their phone data plan. Some people are living in the dark ages. Some people in America are still using modems. Do you want to leave those people out? Possibly, they may not be your target demographic, but it's kind of a jerk move. Also, there are other reasons that people don't have internet. This is a fight I lost at Microsoft and I am still embarrassed about it because what happened was I was working on the 2008 Windows Server. And we had come up with this amazing new plan where you don't get all your help in the build. You download it and that allows us to keep it fresher and more current and reactive and make sure that we're solving all the problems, right? Do you know where servers live? They live in server rooms with ferocious firewall rules and if you're doing it right, no browser because you do not want your servers in your server room exposed to the internet. It's like licking a toilet. So there's no way that you're going to open up a hole in your firewall so that Microsoft can download some unseen packets to solve your server problems. They're like, oh well, they can just go back to their desk and look it up. Do you think the admins had server installed on the computer at their desk? They didn't and they couldn't look up the server help from the desktop that they had. So they had this real problem and I said, we can't do this with server documentation. We have to provide the whole thing and I was insufficiently persuasive and if you've used Windows Server 2008 it has tried to download documentation updates for you. Sorry. So there are a lot of people in the world using old devices and I'd like to say that it's easy to forget how far we've come in phones and tablets and everything. When angry birds switched over to tablet default, I noticed, I'm like, I can't see the birds past the ads. I'm not okay. So I think it's really important to keep a stash of old phones if you're doing any kind of mobile development so that you can see what the load actually looks like. You may also be talking to people who have big fat fingers or can't find their stylus or are, I don't know, just not good at the touchingness. Sometimes I get really cold fingers and the phone doesn't respond to me. So a problem more common in women than men and it's just really frustrating to not be able to use somebody's app because it requires really fine finger control. We are all only temporarily able-bodied. Age is coming for us all. Disability, infirmity, sickness, accident, it's gonna happen to us and we need to be building for ourselves in the future. If I'm not saying be compassionate to other people, that's not sufficiently compelling, be compassionate to your future self. Say, hey, future self, how's that gonna work out? I don't understand. Like, if I can't use my left and right hand, how am I gonna hold my phone and type on it? So remember that we're all only temporarily able to do these things, to type, to touch, to speak. It's gonna change. So you're a bunch of developers and you are paid to complete code in a timely manner to meet project goals. And what I'm trying to get you to do is do work upfront and you're all kind of like, yeah, but I have this deadline. I have this thing. There's a reason I can't do these best practices. Let me ask you this. How much do you really enjoy performing mission-critical tasks on a tight deadline with no particular reward? Because that is not my favorite thing to do and that's what you're going to end up doing if you continue to make these mistakes. So now what? I've made you all sad. You're like, I'm not doing the things that I need to be doing. Write a coding style guide and follow it. That solves a ton of the accessibility problems that you can get. Apple has a nice one. There's some really good stuff out there for write a style guide and follow it. Do some brown bag lunches on how you, as an organization, could do this. You could, for instance, show the talk. They're gonna record it and send it out. You could just have a lunch about this. I'd be famous in your company. Or you can talk about how your particular product could be improved, how you can pay down some of your technical data ahead of time. When you're pair programming, encourage each other to best practices. You can say, hey, I think it would be more accessible if we did this. Hey, I think it would be more secure if we put in SSL. Hey, I think we could improve on this. Add test for accessibility and usability. Even if you don't have a test group, write that into your test plan. Like, how is this usable? How is this secure? How is it accessible? Cultivate diversity and representation on your team. Make sure you have one of those 8% of colorblind guys, right? Or there are other types of diversity that you might wanna throw in that other people think about. Ask questions. Ask users questions. Ask your installers questions. Ask your tech support questions. I guarantee you, whoever is doing tech support knows exactly where your users are failing to succeed. Because the users are calling in going, meh, meh, meh, meh, meh, meh, meh, meh. And they know where the problem is. This is why I always like sitting next to tech support. They know where the problems are. They know where the bodies are buried. So, here are your seven righteous fights in handy slide format. Localization, build it in early so you don't have to build it in at 300 pages. Security, put the encryption in now so you don't have to do it later. Extensibility, make it so that other people can use not just your front end but your back end. Documentation, because it really sucks when you have to try and drag a build engineer out of bed in the middle of night. Affordance, making your product shape behavior that you want. Acceptance, making sure that you are serving your users' needs and accessibility, making sure that everybody can use your product. I'm gonna go back to accessibility for a minute because I forgot something really important. Did you know that software has to meet section 508 of the Americans with Disabilities Act in order to get federal money? If you are not ADA compliant, the feds cannot spend money on you. And you're like, that's okay. I'm not selling to the government. Do you know who that includes? Any higher education or college that includes federal grants, prisons, hospitals, like the world is touched by federal money and federal money is driving this accessibility need. So go look up section 508. It has some really clear outlines on what it is you need to be doing and make sure you are not leaving money on the table by not complying with it. It's like a no-brainer. Like, hey, we're 508 compliant. How about you? No? Guess we can't buy you. Okay, so this talk was too long. I read Twitter. Be productively lazy. When I was a kid, I read the original, not the movie of Cheaper by the Dozen. And it's actually a really interesting story about people who were productivity experts who studied motions in factories. And the thing I got out of it was they would go to a factory and say, who is your laziest worker? Who is the worker who works least hard? And they would film that person because that person had optimized as much as possible to do as little work as possible. I want you to optimize as much as possible in the front end of your products to do as little work as possible in the back end. Gives you more time to do fun things or, you know, sleep. I'm in favor of it. So I can take a few questions and then you can go have lunch or you can go have lunch now. Do I have any advice for winning these fights? I do. The advice is make it about money because it turns out that business owners are reluctant to give you time to work on this until you say, yeah, but it's gonna save us this much money. Like, if we do it now when we only have six pages, it's gonna cost us a day. If we do it later when we have 20 pages, it's gonna cost us three days. So if you make it about money, people listen better. And if you make it about, like, moral force, people blow you off. Like, I'm sorry, that's just the way it is. I care about moral force, but they care about money. Is my point that all of these things are part of the minimum set of features? My point is that you should try to make them part of the minimum set of features. I am enough of a realist to know that you're not going to win all of these fights, but every little hook that you leave in for later, every time you take 30 seconds instead of two seconds to build a link, every time you say, hey, I don't have to hand code that, I could put that in a file, that is your personal rebellion against speed kills because your product, while it may be viable, is not going to be optimal. And so it's always gonna be a balance. Like, I can't tell you, you have to do all of these things to make a viable product. That's not true, but I can tell you, you will pay and pay and pay if you don't do these things super early. Yes, okay, so the question is, there's a lot of problems selling this to your peers and especially junior peers because it doesn't feel productive to them to do this. They're like, we can do that later because they haven't, like me, had this problem happen over and over again. And this is part of why you're going to have to do the socializing in a peer programming way. And I think one of the things you could do is make an hour a week, like accessibility hour, and say, okay, we're all gonna use screen readers for the next hour. Oh, wait, you don't like doing that because it's really terrible with our product? Like, eat your own dog food in more than just generating code. You should eat your own dog food in using your product. And how many of you actually use your product every day? Like, I don't, I open it to document things, but I don't actually use it to do anything. I think it's a really important part of being developers that we don't just make the product that we understand how to use it because otherwise we're failing to make a product, we're making some code. Does that, okay, time for lunch.