Google+

Location

Authors

Name: A List Apart: The Fu...

Location: Not Available

Language: Not Available

Url: Not Available

Create an Evolutionary Web Strategy with a Digital MRO Plan

Many organizations, large and small, approach creating their web presence as if it’s a one-time project. They invest an enormous amount of time and money in a great web design, content strategy, and technical implementation; and then they let the website sit there for months and even years without meaningful updates or enhancements. When the web presence becomes so out of date it’s barely functional, it becomes clear to them that the site needs a refresh (or more likely another full redesign). Redesigns are great. But there’s a better way: ensure your client has a website that continually adapts to their needs. Equip your client with a framework that helps them with ongoing management of their web presence. This plan also ensures you continue to build a strong relationship over the long term. It’s called an MRO plan. MRO stands for Maintenance, Repair, and Overhaul. It’s a term most often used with building facilities or machinery. A house is a machine for living in. Le Corbusier Everyone knows that a building or a piece of heavy machinery needs a regular maintenance plan. Buildings and machines are complex systems that need tuning and maintenance. Websites are also complex systems. You could say, “A website is a machine for engagement.” To keep that engagement running smoothly, your client needs a plan that includes regular maintenance along with content and feature updates. The problem with the curve Typically, websites undergo waves of full redesign, neglect, failure, full redesign. Think of it as a series of bell curves dipping into the negative between revolutionary overhauls. The revolution approach to managing your web presence. Your client comes to you with an initial big push to deliver a new web design and content strategy, something that they will be able to manage without your assistance. And you provide that. But once you walk away, the website stops evolving. During this time, the client’s products or services may evolve, and they may adapt their product-based content to changes in their market—but they don’t touch the website. Like old bread, their website gets stale until the day comes when it’s clear that it needs to be fixed ASAP. That’s when you get the call. There’s a huge drive to do a website redesign, and a big new project is kicked off. You finish the project and walk away. Again. But this is a mistake. It’s smarter to show your client how to implement a plan that protects their investment in their website. It’s smarter for the client, and it’s smarter for you too because it allows you to develop an ongoing relationship that ensures you have recurring revenue over a longer period. Convince your client to break this endless cycle of big, expensive redesign projects every few years. Show them that they need to manage their website the same way they manage product development–by consistently and regularly monitoring and managing their web experience, focusing on ongoing maintenance, interim updates, and major overhauls when needed. Think evolution not revolution A digital MRO plan provides continual investment so websites can evolve in a more consistent manner over time–evolution versus revolution. The evolutionary approach requires your client to regularly update their website based on how their company, the industry, and their customer data is changing. An MRO program for a web presence–the evolution approach. Define an MRO framework for your client with three phases: Maintenance: This is the phase that occurs over a long period, with regular monitoring of web pages, content assets, and other resources in addition to functionality. The maintenance phase is about fixing small things, making small changes or updates that don’t require major work on the website. How you can help: Outline a regular maintenance plan where issues are documented and then packaged together into maintenance updates. In some cases, these fixes are content-based, in other cases they are functionality bugs or small updates that need to be applied. You can work on these maintenance updates monthly or more often depending on the situation, delivering regular changes to the website to keep it up to date. Repair: Repairs are like interim updates. They may require a fair amount of changes to the website to fix a problem or implement a new concept or idea, but they don’t require a full redesign. Some examples include updating or removing a section of the website not visited often, rewriting an outdated key whitepaper, or improving the resources section. They could also include rewrites to web pages for a new version of a product, or the addition of a set of new web pages. How you can help: Whether it’s a set of web pages for a new product, or a redesign of the resources section of the website, recommend quarterly reviews of the website where you can discuss new content or functionality that can be added to the site to improve it for customers and prospects. This requires that you follow trends in both content marketing and design/development, as well as trends in the industry of the client (and their competition). Recommend “mini” projects to implement these interim updates for your client. Overhaul: During an overhaul phase it’s time for that full redesign. Maybe the client is implementing a new brand, and they need to update their website to reflect it. Maybe they need to implement a modern CMS. Overhaul projects take time and big budgets, and typically take place every five or more years. How you can help: Working with the client on a regular basis on maintenance and small repairs enables you to demonstrate your understanding of the client, their needs and their customers’ needs, proving that you are the right one to run the redesign project. Your knowledge of the industry, along with your experience with the website and the technology it lives on makes you the right choice. Recommend a full website review every four to five years to determine if a redesign is necessary, and to demonstrate how you are in the best position to complete the project successfully. Your digital MRO plan should prioritize and align work based on the evolution of the customer’s organization or business, as well as the feedback visitors are giving on the website. Incorporating customer feedback and analytics into your MRO plan provides the insight you need to streamline engagement and helps your customer validate the return on investment from their website. You can use surveys, A/B tests, session cams, heat maps, and web analytics reports to focus on the areas of the site that need updating and prioritize projects into each phase of the MRO plan. The benefits of an MRO program for web presence With a solid MRO plan you can help your client manage their website like they would their products and services: with regular, consistent updates. Creating a digital MRO plan enables you to show your client how they can get more consistent, predictable ROI from their website and other digital channels and streamline their budget. When pitching an MRO program to your client, focus on the following benefits: Budget management: By following an MRO program, costs are spread over a longer period instead of a big outlay of time and money for a large project. Improved customer experience: Implementing web analytics, listening posts, surveys, and feedback programs ensures the client is listening to its customers and delivering on customer needs consistently, improving website engagement. Content is never out of date: Product-based content assets are updated in line with product/service improvements, ensuring the most current information is available on the website. You can also help your client plan additions to marketing content assets or add news in line with product updates. Reduced costs and increased ROI: The website is a primary value driver for every business. It’s the best salesperson, the digital storefront, the manifestation of a brand, and a hub for customer services and support. Keeping the website working well will increase digital ROI and lower costs. Perhaps the biggest benefit of an MRO plan is more successful redesigns. With an MRO program in place, clients can take the guesswork out of large redesign projects. They will have the results of years of optimization to build upon, ensuring that when they do launch the big redesign they will have real data and experience to know what will work. Be an integral part of an MRO plan It’s one thing to recommend and sell a client on following an MRO plan, but it’s another to ensure that you and/or your team are an integral part of that plan. Here are some suggestions on how you can build your time and budget into an MRO plan. Recommend a dedicated cross-functional digital team with time and resources allocated for the website. The team should include capabilities such as a writer, designer, and web developer. Depending on your relationship with the client, one or two of those capabilities, such as content writing/analysis or design and development, should be provided by you or your team. Schedule monthly cross-functional meetings to brainstorm, research, and validate requirements and ideas for website updates and changes. You should have access to website analytics so you can stay informed about the performance of the website. Based on these meetings, help the client package changes into maintenance or interim updates. Suggest a process and budget to handle maintenance updates based on your experience with this client and similar clients. Provide a budget for regular website design and enhancement implementation by you or your team. The scope and regularity of these enhancements will vary based on the needs of the business or organization, but plan for no less than once per quarter. Build in enough time to monitor the client’s industry and competition, as well as review website analytics and content management trends. Recommend a process for completing a full website review driven by you. This takes the burden off the client to plan and coordinate the review and ensures you are part of the review and recommendations for a redesign. A proactive approach For many organizations, the easy route is revolution. It seems easier because it happens only once every few years. But this tactic takes more time and costs much more money up front. An MRO program ensures businesses are strategically managing their web presence and putting in place the ongoing resources to keep it up to date and relevant for their prospects and customers. One of those ongoing resources is you. Build your role into the MRO program, indicating where you can provide services that support different phases of the program. Being involved on a regular basis with maintenance and interim updates demonstrates your understanding of the clients’ needs and ensures you will be the one they come to when the big redesign project happens (and it will happen). Whether you are a single freelancer, a two-person team, or part of a larger agency, the key to building long-term, revenue-generating relationships with clients is getting them to see the value of a proactive approach for website management. An MRO program can help you do that.

1 0 0 0
Login to proceed

Cancel

Ok Cancel


Cancel
Hours
Cancel
The Foundation of Technical Leadership

I’m a front-end architect, but I’m also known as a technical leader, subject matter expert, and a number of other things. I came into my current agency with five years of design and development management experience; yet when it came time to choose a path for my career with the company, I went the technical route. I have to confess I had no idea what a technical leader really does. I figured it out, eventually. Technical experts are not necessarily technical leaders. Both have outstanding technical skills; the difference is in how others relate to you. Are you a person that others want to follow? That’s the question that really matters. Here are some of the soft skills that set a technical leader apart from a technical expert. Help like it’s your job Your authority in a technical leadership position—or any leadership position—is going to arise from what you can do for (or to) other people. Healthy authority here stems from you being known as a tried-and-true problem-solver for everyone. The goal is for other people to seek you out, not for you to be chasing down people for code reviews. For this to happen, intelligence and skill are not enough—you need to make a point of being helpful. For the technical leader, if you’re too busy to help, you’re not doing your job—and I don’t just mean help someone when they come by and ask for help. You may have to set an expectation with your supervisor that helping others is a vital part of a technical leader’s job. But guess what? It might be billable time—check with your boss. Even if it’s not, try to estimate how much time it’s saving your coworkers. Numbers speak volumes. The true measure of how helpful you are is the technical know-how of the entire team. If you’re awesome but your team can’t produce excellent work, you’re not a technical leader—you’re a high-level developer. There is a difference. Every bit of code you write, every bit of documentation you put together should be suitable to use as training for others on your team. When making a decision about how to solve a problem or what technologies to use, think about what will help future developers. My job as front-end architect frequently involves not only writing clean code, but cleaning up others’ code to aid in reusability and comprehension by other developers. That large collection of functions might work better as an object, and it’ll probably be up to you to make that happen, whether through training or just doing it. Speaking of training, it needs to be a passion. Experience with and aptitude for training were probably the biggest factors in me landing the position as front-end architect. Public speaking is a must. Writing documentation will probably fall on you. Every technical problem that comes your way should be viewed as an opportunity to train the person who brought it to you. Helping others, whether they’re other developers, project managers, or clients, needs to become a passion for you if you’re an aspiring technical leader. This can take a lot of forms, but it should permeate into everything you do. That’s why this is rule number one. Don’t throw a mattress into a swimming pool An infamous prank can teach us something about being a technical leader. Mattresses are easy to get into swimming pools; but once they’re in there, they become almost impossible to get out. Really, I worked the math on this: a queen-sized mattress, once waterlogged, will weigh over 2000 pounds. A lot of things are easy to work into a codebase: frameworks, underlying code philosophies, even choices on what technology to use. But once a codebase is built on a foundation, it becomes nearly impossible to get that foundation out of there without rebuilding the entire codebase. Shiny new framework seem like a good idea? You’d better hope everyone on your team knows how to use that framework, and that the framework’s around in six months. Don’t have time to go back and clean up that complex object you wrote to handle all the AJAX functionality? Don’t be surprised when people start writing unneeded workarounds because they don’t understand your code. Did you leave your code in a state that’s hard to read and modify? I want you to imagine a mattress being thrown into a swimming pool… Failure to heed this command frequently results in you being the only person who can work on a particular project. That is never a good situation to be in. Here is one of the big differences between a technical expert and a technical leader: a technical expert could easily overlook that consideration. A technical leader would take steps to ensure that it never happens. As a technical expert, you’re an A player, and that expertise is needed everywhere; and as a technical leader, it’s your job to make sure you can supply it, whether that means training other developers, writing and documenting code to get other developers up to speed, or intentionally choosing frameworks and methodologies your team is already familiar with. Jerry Weinberg, in The Psychology of Computer Programming, said, “If a programmer is indispensable, get rid of him as quickly as possible!” If you’re in a position where you’re indispensable to a long-term project, fixing that needs to be a top priority. You should never be tied down to one project, because your expertise is needed across the team. Before building a codebase on anything, ask yourself what happens when you’re no longer working on the project. If the answer is they have to hire someone smarter than you or the project falls apart, don’t include it in the project. And as a leader, you should be watching others to make sure they don’t make the same mistake. Remember, technology decisions usually fall on the technical leader, no matter who makes them. You’re not the only expert in the room “Because the new program is written for OS 8 and can function twice as fast. Is that enough of a reason, Nancy Drew?” That’s the opening line of Nick Burns, Your Company’s Computer Guy, from the Saturday Night Live sketch with the same name. He’s a technical expert who shows up, verbally abuses you, fixes your computer, and then insults you some more before shouting, “Uh, you’re welcome!” It’s one of those funny-because-it’s-true things. The stereotype of the tech expert who treats everyone else as inferiors is so prevalent that it’s worked its way into comedy skits, television shows, and watercooler conversations in businesses across the nation. I’ve dealt with the guy (or gal). We all have. You know the guy, the one who won’t admit fault, who gets extremely defensive whenever others suggest their own ideas, who views his intellect as superior to others and lets others know it. In fact, everyone who works with developers has dealt with this person at some point. It takes a lot more courage and self-awareness to admit that I’ve been that guy on more than one occasion. As a smart guy, I’ve built my self esteem on that intellect. So when my ideas are challenged, when my intellect is called into question, it feels like a direct assault on my self esteem. And it’s even worse when it’s someone less knowledgeable than me. How dare they question my knowledge! Don’t they know that I’m the technical expert? Instead of viewing teammates as people who know less than you, try to view them as people who know more than you in different areas. Treat others as experts in other fields that you can learn from. That project manager may not know much about your object-oriented approach to the solution, but she’s probably an expert in how the project is going and how the client is feeling about things. Once again, in The Psychology of Computer Programming, Weinberg said, “Treat people who know less than you with respect, deference, and patience.” Take it a step further. Don’t just treat them that way—think of them that way. You’d be amazed how much easier it is to work with equals rather than intellectually inferior minions—and a change in mindset might be all that’s required to make that difference. Intelligence requires clarity It can be tempting to protect our expertise by making things appear more complicated than they are. But in reality, it doesn’t take a lot of intelligence to make something more complicated than it needs to be. It does, however, take a great deal of intelligence to take something complicated and make it easy to understand. If other developers, and non-technical people, can’t understand your solution when you explain it in basic terms, you’ve got a problem. Please don’t hear that as “All good solutions should be simple,” because that’s not the case at all—but your explanations should be. Learn to think like a non-technical person so you can explain things in their terms. This will make you much more valuable as a technical leader. And don’t take for granted that you’ll be around to explain your solutions. Sometimes, you’ll never see the person implementing your solution, but that email you sent three weeks ago will be. Work on your writing skills. Pick up a copy of Steven Pinker’s The Sense of Style and read up on persuasive writing. Start a blog and write a few articles on what your coding philosophies are. The same principle extends to your code. If code is really hard to read, it’s usually not a sign that a really smart person wrote it; in fact, it usually means the opposite. Speaker and software engineer Martin Fowler once said, “Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” Remember: clarity is key. The perception of your intelligence is going to define the reality of your work experience, whether you like it or not. You set the tone Imagine going to the doctor to explain some weird symptoms you’re having. You sit down on the examination bed, a bit nervous and a bit confused as to what’s actually going on. As you explain your condition, the doctor listens with widening eyes and shaking hands. And the more you explain, the worse it gets. This doctor is freaking out. When you finally finish, the doctor stammers, “I don’t know how to handle that!” How would you feel? What would you do? If it were me, I’d start saying goodbye to loved ones, because that’s a bad, bad sign. I’d be in a full-blown panic based on the doctor’s reaction. Now imagine a project manager comes to you and starts explaining the weird functionality needed for a particularly tricky project. As you listen, it becomes clear that this is completely new territory for you, as well as for the company. You’re not even sure if what they’re asking is possible. How do you respond? Are you going to be the crazy doctor above? If you are, I can assure you the project manager will be just as scared as you are, if not more so. I’m not saying you should lie and make something up, because that’s even worse. But learning to say “I don’t know” without a hint of panic in your voice is an art that will calm down project teams, clients, supervisors, and anyone else involved in a project. (Hint: it usually involves immediately following up with, “but I’ll check it out.”) As a technical leader, people will follow your emotional lead as well as your technical lead. They’ll look to you not only for the answers, but for the appropriate level of concern. If people leave meetings with you more worried than they were before, it’s probably time to take a look at how your reactions are influencing them. Real technical leadership Technical leadership is just as people-centric as other types of leadership, and knowing how your actions impact others can make all the difference in the world in moving from technical expert to technical leader. Remember: getting people to follow your lead can be even more important than knowing how to solve technical problems. Ignoring people can be career suicide for a technical leader—influencing them is where magic really happens.

1 0 0 0
Login to proceed

Cancel

Ok Cancel


Cancel
Hours
Cancel
The Future of the Web

Recently the web—via Twitter—erupted in short-form statements that soon made it clear that buttons had been pushed, sides taken, and feelings felt. How many feels? All the feels. Some rash words may have been said. But that’s Twitter for you. It began somewhat innocuously off-Twitter, with a very reasonable X-Men-themed post by Brian Kardell (one of the authors of the Extensible Web Manifesto). Brian suggests that the way forward is by opening up (via JavaScript) some low-level features that have traditionally been welded shut in the browser. This gives web developers and designers—authors, in the parlance of web standards—the ability to prototype future native browser features (for example, by creating custom elements). If you’ve been following all the talk about web components and the shadow DOM of late, this will sound familiar. The idea is to make standards-making a more rapid, iterative, bottom-up process; if authors have the tools to prototype their own solutions or features (poly- and prolly-fills), then the best of these solutions will ultimately rise to the top and make their way into the native browser environments. This sounds empowering, collaborative—very much in the spirit of the web. And, in fact, everything seemed well on the World Wide Web until this string of tweets by Alex Russell, and then this other string of tweets. At which point everyone on the web sort of went bananas. Doomsday scenarios were proclaimed; shadowy plots implied; curt, sweeping ideological statements made. In short, it was the kind of shit-show you might expect from a touchy, nuanced subject being introduced on Twitter. But why is it even touchy? Doesn’t it just sound kind of great? Oh wait JavaScript Whenever you talk about JavaScript as anything other than an optional interaction layer, folks seem to gather into two big groups. On the Extensible Web side, we can see the people who think JavaScript is the way forward for the web. And there’s some historical precedent for that. When Brendan Eich created JavaScript, he was aware that he was putting it all together in a hurry, and that he would get things wrong. He wanted JavaScript to be the escape hatch by which others could improve his work (and fix what he got wrong). Taken one step further, JavaScript gives us the ability to extend the web beyond where it currently is. And that, really, is what the Extensible Web Manifesto folks are looking to do. The web needs to compete with native apps, they assert. And until we get what we need natively in the browser, we can fake it with JavaScript. Much of this approach is encapsulated in the idea of progressive web apps (offline access, tab access, file system access, a spot on the home screen)—giving the web, as Alex Russell puts it, a fair fight. On the other side of things, in the progressive enhancement camp, we get folks that are worried these approaches will leave some users in the dust. This is epitomized by the “what about users with no JavaScript” argument. This polarizing question—though not the entire issue by far—gets at the heart of the disagreement. For the Extensible Web folks, it feels like we’re holding the whole web back for a tiny minority of users. For the Progressive Enhancement folks, it’s akin to throwing out accessibility—cruelly denying access to a subset of (quite possibly disadvantaged) users. During all this hubbub, Jeremy Keith, one of the most prominent torchbearers for progressive enhancement, reminded us that nothing is absolute. He suggests that—as always—the answer is “it depends.” Now this should be pretty obvious to anyone who’s spent a few minutes in the real world doing just about anything. And yet, at the drop of a tweet, we all seem to forget it. So if we can all take a breath and rein in our feelings for a second, how might we better frame this whole concept of moving the web forward? Because from where I’m sitting, we’re all actually on the same side. History and repetition To better understand the bigger picture about the future of the web, it’s useful (as usual) to look back at its past. Since the very beginning of the web, there have been disagreements about how best to proceed. Marc Andreessen and Tim Berners-Lee famously disagreed about the IMG tag. Tim didn’t get his way, Marc implemented IMG in Mosaic as he saw fit, and we all know how things spun out from there. It wasn’t perfect, but a choice had to be made and it did the job. History suggests that IMG did its job fairly well. A pattern of hacking our way to the better solution becomes evident when you follow the trajectory of the web’s development. In the 1990’s, webmasters and designers wanted layout like they were used to in print. They wanted columns, dammit. David Siegel formalized the whole tables-and-spacer-GIFs approach in his wildly popular book Creating Killer Web Sites. And thus, the web was flooded with both design innovation and loads of un-semantic markup. Which we now know is bad. But those were the tools that were available, and they allowed us to express our needs at the time. Life, as they say…finds a way. And when CSS layout came along, guess what it used as a model for the kinds of layout techniques we needed? That’s right: tables. While we’re at it, how about Flash? As with tables, I’m imagining resounding “boos” from the audience. “Boo, Flash!” But if Flash was so terrible, why did we end up with a web full of Flash sites? I’ll tell you why: video, audio, animation, and cross-browser consistency. In 1999? Damn straight I want a Flash site. Once authors got their hands on a tool that let them do all those incredible things, they brought the world of web design into a new era of innovation and experimentation. But again with the lack of semantics, linkability, and interoperability. And while we were at it, with the tossing out of an open, copyright-free platform. Whoops. It wasn’t long, though, before the native web had to sit up and take notice. Largely because of what authors expressed through Flash, we ended up with things like HTML5, Ajax, SVGs, and CSS3 animations. We knew the outcomes we wanted, and the web just needed to evolve to give us a better solution than Flash. In short: to get where we need to go, we have to do it wrong first. Making it up as we go along We authors express our needs with the tools available to help model what we really need at that moment. Best practices and healthy debate are a part of that. But please, don’t let the sort of emotions we attach to politics and religion stop you from moving forward, however messily. Talk about it? Yes. But at a certain point we all need to shut our traps and go build some stuff. Build it the way you think it should be built. And if it’s good—really good—everyone will see your point. If I said to you, “I want you to become a really great developer—but you’re not allowed to be a bad developer first,” you’d say I was crazy. So why would we say the same thing about building the web? We need to try building things. Probably, at first, bad things. But the lessons learned while building those “bad” projects point the way to the better version that comes next. Together we can shuffle toward a better way, taking steps forward, back, and sometimes sideways. But history tells us that we do get there. The web is a mess. It is, like its creators, imperfect. It’s the most human of mediums. And that messiness, that fluidly shifting imperfection, is why it’s survived this long. It makes it adaptable to our quickly-shifting times. As we try to extend the web, we may move backward at the same time. And that’s OK. That imperfect sort of progress is how the web ever got anywhere at all. And it’s how it will get where we’re headed next. Context is everything One thing that needs to be considered when we’re experimenting (and building things that will likely be kind of bad) is who the audience is for that thing. Will everyone be able to use it? Not if it’s, say, a tool confined to a corporate intranet. Do we then need to worry about sub-3G network users? No, probably not. What about if we’re building on the open web but we’re building a product that is expressly for transferring or manipulating HD video files? Do we need to worry about slow networks then? The file sizes inherent in the product pretty much exclude slow networks already, so maybe that condition can go out the window there, too. Context, as usual, is everything. There needs to be realistic assessment of the risk of exclusion against the potential gains of trying new technologies and approaches. We’re already doing this, anyway. Show me a perfectly progressively enhanced, perfectly accessible, perfectly performant project and I’ll show you a company that never ships. We do our best within the constraints we have. We weigh potential risks and benefits. And then we build stuff and assess how well it went; we learn and improve. When a new approach we’re trying might have aspects that are harmful to some users, it’s good to raise a red flag. So when we see issues with one another’s approaches, let’s talk about how we can fix those problems without throwing out the progress that’s been made. Let’s see how we can bring greater experiences to the web without leaving users in the dust. If we can continue to work together and consciously balance these dual impulses—pushing the boundaries of the web while keeping it open and accessible to everyone—we’ll know we’re on the right track, even if it’s sometimes a circuitous or befuddling one. Even if sometimes it’s kind of bad. Because that’s the only way I know to get to good.

1 0 0 0
Login to proceed

Cancel

Ok Cancel


Cancel
Hours
Cancel
Help One of Our Own: Carolyn Wood

One of the nicest people we’ve ever known and worked with is in a desperate fight to survive. Many of you remember her—she is a gifted, passionate, and tireless worker who has never sought the spotlight and has never asked anything for herself. Carolyn Wood spent three brilliant years at A List Apart, creating the position of acquisitions editor and bringing in articles that most of us in the web industry consider essential reading—not to mention more than 100 others that are equally vital to what we do today. Writers loved her. Since 1999, she has also worked on great web projects like DigitalWeb, The Manual, and Codex: The Journal of Typography. Think about it. What would the web look like if she hadn’t been a force behind articles like these: Responsive Web Design by Ethan Marcotte More Meaningful Typography by Tim Brown Orbital Content by Cameron Koczon CSS Floats 101 by Noah Stokes Designing Web Registration Processes for Kids by Debra Levin Gelman Design Criticism and the Creative Process by Cassie McDaniel A Simpler Page by Craig Mod Three years ago, Carolyn was confined to a wheelchair. Then it got worse. From the YouCaring page: This April, after a week-long illness, she developed acute injuries to the tendons in her feet and the nerves in her right hand and arm. She couldn’t get out of her wheelchair, even to go to the bathroom. At the hospital, they discovered Carolyn had acute kidney failure. After a month in a hospital and a care facility she has bounced back from the kidney failure, but she cannot take painkillers to help her hands and feet.Carolyn cannot stand or walk or dress herself or take a shower. She is dependent on a lift, manned by two people, to transfer her. Without it she cannot leave her bed.She’s now warehoused in a home that does not provide therapy—and her insurance does not cover the cost. Her bills are skyrocketing. (She even pays rent on her bed for $200 a month!)Perhaps worst of all—yes, this gets worse—is that her husband has leukemia. He’s dealing with his own intense pain and fatigue and side effects from twice-monthly infusions. They are each other’s only support, and have been living apart since April. They have no income other than his disability, and are burning through their life savings. This is absolutely a crisis situation. We’re pulling the community together to help Carolyn—doing anything we possibly can. Her bills are truly staggering. She has no way to cover basic life expenses, much less raise the huge sums required to get the physical and occupational therapy she needs to be independent again. Please help by donating anything you can, and by sharing Carolyn’s support page with anyone in your network who is compassionate and will listen.

1 0 0 0
Login to proceed

Cancel

Ok Cancel


Cancel
Hours
Cancel
Promoting a Design System Across Your Products

The scene: day one of a consulting gig with a new client to build a design and code library for a web app. As luck would have it, the client invited me to sit in on a summit of 25 design leaders from across their enterprise planning across platforms and lines of business. The company had just exploded from 30 to over 100 designers. Hundreds more were coming. Divergent product design was everywhere. They dug in to align efforts. From a corner, I listened quietly. I was the new guy, minding my own business, comfortable with my well-defined task and soaking up strategy. Then, after lunch, the VP of Digital Design pulled me into an empty conference room. “Can you refresh me on your scope?” she asked. So I drew an account hub on the whiteboard. “See, the thing is…” she responded, standing up and taking my pen. “We’re redesigning our web marketing homepage now.” She added a circle. “We’re also reinventing online account setup.” Another circle, then arrows connecting the three areas. “We’ve just launched some iOS apps, and more—plus Android—are coming.” She added more circles, arrows, more circles. “I want it all cohesive. Everything.” She drew a circle around the entire ecosystem. “Our design system should cover all of this. You can do that, right?” A long pause, then a deep breath. Our design system—the parts focused on, the people involved, the products reached—had just grown way more complicated. Our industry is getting really good at surfacing reusable parts in a living style guide: visual language like color and typography, components like buttons and forms, sophisticated layouts, editorial voice and tone, and so on. We’ve also awoken to the challenges of balancing the centralized and federated influence of the people involved. But there’s a third consideration: identifying and prioritizing the market of products our enterprise creates that our system will reach. As a systems team, we need to ask: what products will use our system and how will we involve them? Produce a product inventory While some enterprises may have an authoritative and up-to-date master list of products, I’ve yet to work with one. There’s usually no more than a loose appreciation of a constantly evolving product portfolio. Start with a simple product list A simple list is easy enough. Any whiteboard or text file will do. Produce the list quickly by freelisting as many products as you can think of with teammates involved in starting the system. List actual products (“Investor Relations” and “Careers”), not types of products (such as “Corporate Subsites”). Some simple product lists Large Corporate Web Site Small Product Company Large Enterprise 5–15 products 10–25 products 20–100 products Homepage Products Support About Careers Web marketing site Web support site Web corporate site Community site 1 Community site 2 Web app basic Web app premium Web app 3 Web app 4 Windows flagship client Windows app 2 Web home Web product pages Web product search Web checkout Web support Web rewards program iOS apps (10+) Android apps (10+) Web account mgmt (5+) Web apps (10+) ⋮ Note that because every enterprise is unique, the longer the lists get, the more specific they become. For broader portfolios, gather more details If your portfolio is more extensive, you’ll need more deliberate planning and coordination of teams spanning an organization. This calls for a more structured, detailed inventory. It’s spreadsheet time, with products as rows and columns for the following: Name, such as Gmail Type / platform: web site, web app, iOS, Android, kiosk, etc. Product owner, if that person even exists Description (optional) People (optional), like a product manager, lead designer or developer, or others involved in the product Other metadata (optional): line of business, last redesigned, upcoming redesign, tech platform, etc. A detailed product inventory. Creating such an inventory can feel draining for a designer. Some modern digital organizations struggle to fill out an inventory like this. I’m talking deer-in-headlights kind of struggling. Completely locked up. Can’t do it. But consider life without it: if you don’t know the possible players, you may set yourself up for failure, or at least a slower road to success. Therefore, take the time to understand the landscape, because the next step is choosing the right products to work with. Prioritize products into tiers A system effort is never equally influenced by every product it serves. Instead, the system must know which products matter—and which don’t—and then varyingly engage each in the effort. You can quickly gather input on product priorities from your systems team and/or leaders using techniques like cumulative voting. Your objective is to classify products into tiers, such as Flagship (the few, essential core products), Secondary (additional influential products), and The Rest to orient strategy and clarify objectives. 1—Organize around flagships Flagship products are the limited number of core products that a system team deeply and regularly engages with. These products reflect a business’ core essence and values, and their adoption of a system signals the system’s legitimacy. Getting flagship products to participate is essential, but challenging. Each usually has a lot of individual power and operates autonomously. Getting flagships to share and realize a cohesive objective requires effort. Choose flagships that’ll commit to you, too When naming flagships, you must believe they’ll play nice and deliver using the system. Expect to work to align flagships: they can be established, complicated, and well aware of their flagship status. Nevertheless, if all flagships deliver using the system, the system is an unassailable standard. If any avoid or obstruct the system, the system lacks legitimacy. Takeaway: obtain firm commitments, such as “We will ship with the system by such and such a date” or “Our product MVP must use this design system.” A looser “Yes, we’ll probably adopt what we can” lacks specificity and fidelity. Latch onto a milestone, or make your own Flagship commitment can surface as a part of a massive redesign, corporate rebranding, or executive decree. Those are easy events to organize around. Without one, you’ll need to work harder bottom-up to align product managers individually. Takeaway: establish a reasonable adoption milestone you can broadcast, after which all flagships have shipped with the system. Choose wisely (between three and five) For a system to succeed, flagships must ship with it. So choose just enough. One flagship makes the system’s goals indistinguishable from its own self-interest. Two products don’t offer enough variety of voices and contexts to matter. Forming a foundation with six or more “equally influential voices” can become chaotic. Takeaway: three flagships is the magic minimum, offering sufficient range and incorporating an influential and sometimes decisive third perspective. Allowing for four or five flagships is feasible but will test a group’s ability to work together fluidly. A system for many must be designed by many Enterprises place top talent on flagship products. It would be naive to think that your best and brightest will absorb a system that they don’t influence or create themselves. It’s a team game, and getting all-stars working well together is part of your challenge. Takeaway: integrate flagship designers from the beginning, as you design the system, to inject the right blend of individual styles and shared beliefs. 3—Blend in a secondary set More products—a secondary set— are also important to a system’s success. Such products may not be flagships because they are between major releases (making adoption difficult), not under active development, or even just slightly less valuable. Include secondary products in reference designs Early systems efforts can explore concept mockups—also known as reference designs—to assess a new visual language across many products. Reference designs reveal an emerging direction and serve as “before and after” roadshow material. Takeaway: include secondary products in early design concepts to acknowledge the value of those products, align the system with their needs, and invite their teams to adopt the system early. Welcome participation (but moderate contribution) Systems benefit from an inclusive environment, so bias behaviors toward welcoming input. Encourage divergent ideas, but know that it’s simply not practical to give everyone a voice in everything. Jon Wiley, an early core contributor to Google’s Material Design, shared some wisdom with me during a conversation: “The more a secondary product’s designer participated and injected value, the more latitude they got to interpret and extend the system for their context.” Takeaway: be open to—but carefully moderate—the involvement of designers on secondary products. 3—Serve the rest at a greater distance The bigger the enterprise, the longer and more heterogeneous the long tail of other products that could ultimately adopt the system. A system’s success is all about how you define and message it. For example, adopting the core visual style might be expected, but perhaps rigorous navigational integration and ironclad component consistency aren’t goals. Documentation may be your primary—or only—channel to communicate how to use the system. Beyond that, your budding system team may not have the time for face-to-face meetings or lengthy discussions. Takeaway: early on, limit focus on and engagement with remaining products. As a system matures, gradually invest in lightweight support activities like getting-started sessions, audits, and triaging office-hour clinics. Adjust approach depending on context Every product portfolio is different, and thus so is every design system. Let’s consider the themes and dynamics from some archetypal contexts we face repeatedly in our work. Example 1: large corporate website, made of “properties” You know: the homepage-as-gateway-to-products hegemon (owned by Marketing) integrated with Training, Services, and About Us content (owned by less powerful fiefdoms) straddling a vast ocean of transactional features like Support/Account Management and Communities. All of these “properties” have drifted apart, and some trigger—the decision to go responsive, a rebranding, or an annoyed-enough-to-care executive—dictates that it’s “time to unify!” Typical web marketing sitemap, overlaid with a product section team’s choices on spreading a system beyond its own section. The get? Support System influence usually radiates from Marketing and Brand through to selling Products. But Support is where customers spend most of their time: billing, admin, downloading, troubleshooting. Support’s features are complicated, with intricate UI and longer release cycles across multiple platforms. It may be the most difficult section to integrate , but it’s essential. Takeaway: if your gets—in this case Home, Products, and Support—deliver, you win. Everyone else will either follow or look bad. That’s your flagship set. Minimize homepage distraction Achieving cohesive design is about suffusing an entire experience with it. Yet a homepage is often the part of a site that is most exposed to, and justifiably distinct from, otherwise reusable componentry. It has tons of cooks, unique and often complex parts, and changes frequently. Such qualities— indecisiveness, complexity, and instability—corrode systems efforts. Takeaway: don’t fall prey to the homepage distraction. Focus on stable fundamentals that you can confidently spread. Exploit navigational change to integrate a system hook As branding or navigation changes, so does a header. It appears everywhere, and changes to it can be propagated centrally. Get those properties—particularly those lacking full-time design support—to sync with a shared navigation service, and use that hook to open access to the greater goodies your system has to offer. Takeaway: exploit the connection! Adopters may not embrace all your parts, but since you are injecting your code into their environment, they could. Example 2: a modest product portfolio A smaller company’s strategic shifts can be chaotic, lending themselves to an unstable environment in which to apply a system. Nevertheless, a smaller community of designers—often a community of practice dispersed across a portfolio—can provide an opportunity to be more cohesive. Radiate influence from web apps Many small companies assemble portfolios of websites, web apps, and their iOS, Android, and Windows counterparts. Websites and native apps share little beyond visual style and editorial tone. However, web apps provide a pivot: they can share a far deeper overlap of components and tooling with websites, and their experiences often mirror what’s found on native apps. Takeaway: look for important products whose interests overlap many other products, and radiate influence from there. Diagram of product relationships within a portfolio, with web apps relating to both web sites and native apps. Demo value across the whole journey A small company’s flagship products should be the backbone of a customer’s journey, from reach and acquisition through service and loyalty. Design activities that express the system’s value from the broader user journey tend to reveal gaps, identify clunky handoffs, and trigger real discussions around cohesiveness. Takeaway: evoke system aspirations by creating before/after concepts and demoing cohesiveness across the journey, such as with a stitched prototype. For Marriott.com, disparate design artifacts across products (left) were stitched together into an interactive, interconnected prototype (right). Bridge collaboration beyond digital Because of their areas of focus, “non-digital” designers (working on products like trade-show booths, print, TV, and retail) tend to be less savvy than their digital counterparts when it comes to interaction. Nonetheless, you’ll share the essence of your visual language with them, such as making sure the system’s primary button doesn’t run afoul of the brand’s blue, and yet provides sufficient contrast for accessibility. Takeaway: encourage non-digital designers to do digital things. Be patient and inclusive, even if their concerns sometimes drift away from what you care about most. Example 3: a massive multiplatform enterprise For an enterprise as huge as Google, prioritizing apps was essential to Material Design’s success. The Verge’s “Redesigning Google: How Larry Page Engineered a Beautiful Revolution” suggests strong prioritization, with Search, Maps, Gmail, and later Android central to the emerging system. Not as much in the conversation, perhaps early on? Docs, Drive, Books, Finance. Definitely not SantaTracker. Broaden representation across platforms & businesses With coverage across a far broader swath of products, ensure flagship product selection spans a few platforms and lines of business. If you want it to apply everywhere, then the system—how it’s designed, developed, and maintained—will benefit from diverse influences. Takeaway: Strive for diverse system contribution and participation in a manner consistent with the products it serves. Mix doers & delegators Massive enterprise systems trigger influence from many visionaries. Yet you can’t rely on senior directors to produce meticulous, thoughtful concepts. Such leaders already direct and manage work across many products. Save them from themselves! Work with them to identify design talent with pockets of time. Even better, ask them to lend a doer they recommend for a month- or weeklong burst. Takeaway: defer to creative leaders on strategy, but redirect their instincts from doing everything to identifying and providing talent. Right the fundamentals before digging deep I confess that in the past, I’ve brought a too-lofty ambition to bear on quickly building huge libraries for organizations of many, many designers. Months later, I wondered why our team was still refining the “big three” (color, typography, and iconography) or the “big five” (the big three, plus buttons and forms). Um, what? Given the system’s broad reach, I had to adjust my expectations to be satisfied with what was still a very consequential shift toward cohesiveness. Takeaway: balance ambition for depth with spreading fundamentals wide across a large enterprise, so that everyone shares a core visual language. The long game Approach a design system as you would a marathon, not a sprint. You’re laying the groundwork for an extensive effort. By understanding your organization through its product portfolio, you’ll strengthen a cornerstone—the design system—that will help you achieve a stronger and more cohesive experience.

1 0 0 0
Login to proceed

Cancel

Ok Cancel


Cancel
Hours
Cancel
Making your JavaScript Pure

Once your website or application goes past a small number of lines, it will inevitably contain bugs of some sort. This isn’t specific to JavaScript but is shared by nearly all languages—it’s very tricky, if not impossible, to thoroughly rule out the chance of any bugs in your application. However, that doesn’t mean we can’t take precautions by coding in a way that lessens our vulnerability to bugs. Pure and impure functions A pure function is defined as one that doesn’t depend on or modify variables outside of its scope. That’s a bit of a mouthful, so let’s dive into some code for a more practical example. Take this function that calculates whether a user’s mouse is on the left-hand side of a page, and logs true if it is and false otherwise. In reality your function would probably be more complex and do more work, but this example does a great job of demonstrating: function mouseOnLeftSide(mouseX) { return mouseX < window.innerWidth / 2; } document.onmousemove = function(e) { console.log(mouseOnLeftSide(e.pageX)); }; mouseOnLeftSide() takes an X coordinate and checks to see if it’s less than half the window width—which would place it on the left side. However, mouseOnLeftSide() is not a pure function. We know this because within the body of the function, it refers to a value that it wasn’t explicitly given: return mouseX < window.innerWidth / 2; The function is given mouseX, but not window.innerWidth. This means the function is reaching out to access data it wasn’t given, and hence it’s not pure. The problem with impure functions You might ask why this is an issue—this piece of code works just fine and does the job expected of it. Imagine that you get a bug report from a user that when the window is less than 500 pixels wide the function is incorrect. How do you test this? You’ve got two options: You could manually test by loading up your browser and moving your mouse around until you’ve found the problem. You could write some unit tests (Rebecca Murphey’s Writing Testable JavaScript is a great introduction) to not only track down the bug, but also ensure that it doesn’t happen again. Keen to have a test in place to avoid this bug recurring, we pick the second option and get writing. Now we face a new problem, though: how do we set up our test correctly? We know we need to set up our test with the window width set to less than 500 pixels, but how? The function relies on window.innerWidth, and making sure that’s at a particular value is going to be a pain. Benefits of pure functions Simpler testing With that issue of how to test in mind, imagine we’d instead written the code like so: function mouseOnLeftSide(mouseX, windowWidth) { return mouseX < windowWidth / 2; } document.onmousemove = function(e) { console.log(mouseOnLeftSide(e.pageX, window.innerWidth)); }; The key difference here is that mouseOnLeftSide() now takes two arguments: the mouse X position and the window width. This means that mouseOnLeftSide() is now a pure function; all the data it needs it is explicitly given as inputs and it never has to reach out to access any data. In terms of functionality, it’s identical to our previous example, but we’ve dramatically improved its maintainability and testability. Now we don’t have to hack around to fake window.innerWidth for any tests, but instead just call mouseOnLeftSide() with the exact arguments we need: mouseOnLeftSide(5, 499) // ensure it works with width < 500 Self-documenting Besides being easier to test, pure functions have other characteristics that make them worth using whenever possible. By their very nature, pure functions are self-documenting. If you know that a function doesn’t reach out of its scope to get data, you know the only data it can possibly touch is passed in as arguments. Consider the following function definition: function mouseOnLeftSide(mouseX, windowWidth) You know that this function deals with two pieces of data, and if the arguments are well named it should be clear what they are. We all have to deal with the pain of revisiting code that’s lain untouched for six months, and being able to regain familiarity with it quickly is a key skill. Avoiding globals in functions The problem of global variables is well documented in JavaScript—the language makes it trivial to store data globally where all functions can access it. This is a common source of bugs, too, because anything could have changed the value of a global variable, and hence the function could now behave differently. An additional property of pure functions is referential transparency. This is a rather complex term with a simple meaning: given the same inputs, the output is always the same. Going back to mouseOnLeftSide, let’s look at the first definition we had: function mouseOnLeftSide(mouseX) { return mouseX < window.innerWidth / 2; } This function is not referentially transparent. I could call it with the input 5 multiple times, resize the window between calls, and the result would be different every time. This is a slightly contrived example, but functions that return different values even when their inputs are the same are always harder to work with. Reasoning about them is harder because you can’t guarantee their behavior. For the same reason, testing is trickier, because you don’t have full control over the data the function needs. On the other hand, our improved mouseOnLeftSide function is referentially transparent because all its data comes from inputs and it never reaches outside itself: function mouseOnLeftSide(mouseX, windowWidth) { return mouseX < windowWidth / 2; } You get referential transparency for free when following the rule of declaring all your data as inputs, and by doing this you eliminate an entire class of bugs around side effects and functions acting unexpectedly. If you have full control over the data, you can hunt down and replicate bugs much more quickly and reliably without chancing the lottery of global variables that could interfere. Choosing which functions to make pure It’s impossible to have pure functions consistently—there will always be a time when you need to reach out and fetch data, the most common example of which is reaching into the DOM to grab a specific element to interact with. It’s a fact of JavaScript that you’ll have to do this, and you shouldn’t feel bad about reaching outside of your function. Instead, carefully consider if there is a way to structure your code so that impure functions can be isolated. Prevent them from having broad effects throughout your codebase, and try to use pure functions whenever appropriate. Let’s take a look at the code below, which grabs an element from the DOM and changes its background color to red: function changeElementToRed() { var foo = document.getElementById('foo'); foo.style.backgroundColor = "red"; } changeElementToRed(); There are two problems with this piece of code, both solvable by transitioning to a pure function: This function is not reusable at all; it’s directly tied to a specific DOM element. If we wanted to reuse it to change a different element, we couldn’t. This function is hard to test because it’s not pure. To test it, we would have to create an element with a specific ID rather than any generic element. Given the two points above, I would rewrite this function to: function changeElementToRed(elem) { elem.style.backgroundColor = "red"; } function changeFooToRed() { var foo = document.getElementById('foo'); changeElementToRed(foo); } changeFooToRed(); We’ve now changed changeElementToRed() to not be tied to a specific DOM element and to be more generic. At the same time, we’ve made it pure, bringing us all the benefits discussed previously. It’s important to note, though, that I’ve still got some impure code—changeFooToRed() is impure. You can never avoid this, but it’s about spotting opportunities where turning a function pure would increase its readability, reusability, and testability. By keeping the places where you’re impure to a minimum and creating as many pure, reusable functions as you can, you’ll save yourself a huge amount of pain in the future and write better code. Conclusion “Pure functions,” “side effects,” and “referential transparency” are terms usually associated with purely functional languages, but that doesn’t mean we can’t take the principles and apply them to our JavaScript, too. By being mindful of these principles and applying them wisely when your code could benefit from them you’ll gain more reliable, self-documenting codebases that are easier to work with and that break less often. I encourage you to keep this in mind next time you’re writing new code, or even revisiting some existing code. It will take some time to get used to these ideas, but soon you’ll find yourself applying them without even thinking about it. Your fellow developers and your future self will thank you.

1 0 0 0
Login to proceed

Cancel

Ok Cancel


Cancel
Hours
Cancel
Commit to Contribute

One morning I found a little time to work on nodemon and saw a new pull request that fixed a small bug. The only problem with the pull request was that it didn’t have tests and didn’t follow the contributing guidelines, which results in the automated deploy not running. The contributor was obviously extremely new to Git and GitHub and just the small change was well out of their comfort zone, so when I asked for the changes to adhere to the way the project works, it all kind of fell apart. How do I change this? How do I make it easier and more welcoming for outside developers to contribute? How do I make sure contributors don’t feel like they’re being asked to do more than necessary? This last point is important. The real cost of a one-line change Many times in my own code, I’ve made a single-line change that could be a matter of a few characters, and this alone fixes an issue. Except that’s never enough. (In fact, there’s usually a correlation between the maturity and/or age of the project and the amount of additional work to complete the change due to the growing complexity of systems over time.) A recent issue in my Snyk work was fixed with this single line change: In this particular example, I had solved the problem in my head very quickly and realized that this was the fix. Except that I had to then write the test to support the change, not only to prove that it works but to prevent regression in the future. My projects (and Snyk’s) all use semantic release to automate releases by commit message. In this particular case, I had to bump the dependencies in the Snyk command line and then commit that with the right message format to ensure a release would inherit the fix. All in all, the one-line fix turned into this: one line, one new test, tested across four versions of node, bump dependencies in a secondary project, ensure commit messages were right, and then wait for the secondary project’s tests to all pass before it was automatically published. Put simply: it’s never just a one-line fix. Helping those first pull requests Doing a pull request (PR) into another project can be pretty daunting. I’ve got a fair amount of experience and even I’ve started and aborted pull requests because I found the chain of events leading up to a complete PR too complex. So how can I change my projects and GitHub repositories to be more welcoming to new contributors and, most important, how can I make that first PR easy and safe? Issue and pull request templates GitHub recently announced support for issue and PR templates. These are a great start because now I can specifically ask for items to be checked off, or information to be filled out to help diagnose issues. Here’s what the PR template looks like for Snyk’s command line interface (CLI) : - [ ] Ready for review - [ ] Follows CONTRIBUTING rules - [ ] Reviewed by @remy (Snyk internal team) #### What does this PR do? #### Where should the reviewer start? #### How should this be manually tested? #### Any background context you want to provide? #### What are the relevant tickets? #### Screenshots #### Additional questions This is partly based on QuickLeft’s PR template. These items are not hard prerequisites on the actual PR, but it does help in getting full information. I’m slowly adding these to all my repos. In addition, having a CONTRIBUTING.md file in the root of the repo (or in .github) means new issues and PRs include the notice in the header: Automated checks For context: semantic release will read the commits in a push to master, and if there’s a feat: commit, it’ll do a minor version bump. If there’s a fix: it’ll do a patch version bump. If the text BREAKING CHANGE: appears in the body of a commit, it’ll do a major version bump. I’ve been using semantic release in all of my projects. As long as the commit message format is right, there’s no work involved in creating a release, and no work in deciding what the version is going to be. Something that none of my repos historically had was the ability to validate contributed commits for formatting. In reality, semantic release doesn’t mind if you don’t follow the commit format; they’re simply ignored and don’t drive releases (to npm). I’ve since come across ghooks, which will run commands on Git hooks, in particular using a commit-msg hook validate-commit-msg. The installation is relatively straightforward, and the feedback to the user is really good because if the commit needs tweaking to follow the commit format, I can include examples and links. Here’s what it looks like on the command line: ...and in the GitHub desktop app (for comparison): This is work that I can load on myself to make contributing easier, which in turn makes my job easier when it comes to managing and merging contributions into the project. In addition, for my projects, I’m also adding a pre-push hook that runs all the tests before the push to GitHub is allowed. That way if new code has broken the tests, the author is aware. To see the changes required to get the output above, see this commit in my current tinker project. There are two further areas worth investigating. The first is the commitizenproject. Second, what I’d really like to see is a GitHub bot that could automatically comment on pull requests to say whether the commits are okay (and if not, direct the contributor on how to fix that problem) and also to show how the PR would affect the release (i.e., whether it would trigger a release, either as a bug patch or a minor version change). Including example tests I think this might be the crux of problem: the lack of example tests in any project. A test can be a minefield of challenges, such as these: knowing the test framework knowing the application code knowing about testing methodology (unit tests, integration, something else) replicating the test environment Another project of mine, inliner, has a disproportionately high rate of PRs that include tests. I put that down to the ease with which users can add tests. The contributing guide makes it clear that contributing doesn’t even require that you write test code. Authors just create a source HTML file and the expected output, and the test automatically includes the file and checks that the output is as expected. Adding specific examples of how to write tests will, I believe, lower the barrier of entry. I might link to some sort of sample test in the contributing doc, or create some kind of harness (like inliner does) to make it easy to add input and expected output. Fixing common mistakes Something I’ve also come to accept is that developers don’t read contributing docs. It’s okay, we’re all busy, we don’t always have time to pore over documentation. Heck, contributing to open source isn’t easy. I’m going to start including a short document on how to fix common problems in pull requests. Often it’s amending a commit message or rebasing the commits. This is easy for me to document, and will allow me to point new users to a walkthrough of how to fix their commits. What’s next? In truth, most of these items are straightforward and not much work to implement. Sure, I wouldn’t drop everything I’m doing and add them to all my projects at once, but certainly I’d include them in each active project as I work on it. Add issue and pull request templates. Add ghooks and validate-commit-msg with standard language (most if not all of my projects are node-based). Either make adding a test super easy, or at least include sample tests (for unit testing and potentially for integration testing). Add a contributing document that includes notes about commit format, tests, and anything that can make the contributing process smoother. Finally, I (and we) always need to keep in mind that when someone has taken time out of their day to contribute code to our projects—whatever the state of the pull request—it’s a big deal. It takes commitment to contribute. Let’s show some love for that.

1 0 0 0
Login to proceed

Cancel

Ok Cancel


Cancel
Hours
Cancel