Оценка на читателите: / 9
Слаба статияОтлична статия 

Новини от света на уеб дизайна и СЕО

Представям Ви синдикирани новини от няколко от водещите сайтове в областта на уеб дизайна и СЕО - оптимизирането за търсачки.

A List Apart: The Full Feed
Articles for people who make web sites.
  • Make Something Great: Become an Open Source Contributor

    My first contribution to Bootstrap was a tiny line of CSS. It was a no-brainer to merge, but the feeling of seeing that bit of code in the project’s codebase was unreal and addictive.

    You may think that open source is not for you. After all, it has always been a developer-dominant ecosystem. But code is by no means the only thing a piece of software is made of. Open source is first and foremost about community. Whether you’re a designer, developer, writer, doctor, or lawyer, there are many paths to the open source world.

    Learn what you need to know to set out on your journey, from first steps to becoming a core contributor. It might change your career.

    It’s OK if you don’t code

    Developers think about their work logically. They break problems down into solvable pieces to make things work. They will devote themselves to crafting an API or a data structure, and optimize those solutions for performance and reusability. Unfortunately, this deconstruction often results in a Swiss Army knife of an interface, with a design that reflects the underlying data structures and APIs available.

    Diversity is what can take open source from where it is to where it could be.
    Una Kravets, “Open Source Design: A Call to Arms

    This is why the open source community needs you. Not only diversity in perspective, but also diversity of gender, location, cultures, and social backgrounds. Together these become greater than the sum of their parts.

    Designers

    Most people who contribute to an open source project are also users of the software. But designers look at the project from a different perspective. Their job is to defend the user, especially those that are not able to contribute to the project but still need the software. They make sure that everyone working on the project understands users’ needs and stays focused on them as the community makes decisions.

    Writers

    Let’s face it: writing is really hard! Designers and developers are usually bad at it. But it’s so valuable to an open source community, where members have to collaborate and communicate remotely, asynchronously, and, more often than not, in a non-native language.

    Documentation, especially on open source projects, is rarely up-to-date. It’s worse when it involves the documentation meant for contributors. Information for getting started with a project frequently has gaps, with important information missing.

    Also, like developers who dedicate themselves to different pieces of a software project, different types of writers can contribute to different pieces of a project’s messaging. They can team up with designers and subject matter experts to write copy for user interfaces, landing pages, or help documentation.

    Geertjan Wielenga was a technical writer in the NetBeans community. Through his documentation, articles, and getting-started guides, he helped thousands of Java developers navigate their way around the project. His contributions had a profound impact, and he became the most acclaimed person in the community.

    Without communication, you have no community. What you write may be the reason why someone decides to get involved. It can make the difference between someone feeling welcome or feeling lost. Your contribution as a writer is invaluable.

    Developers that don’t want to code

    Coding is optional; even software developers don’t always code. There’s administrative work too! Replying to issues, reviewing contributions, and helping users on forums, chats, Reddit, or Stack Overflow is as important to the success of the project as writing code.

    Subject matter experts

    Participation in open source projects is by no means limited to software engineers, designers, and writers. Lawyers, other engineers, and even medical doctors and other specialists can find a place to apply their knowledge too.

    So if you thought open source projects were just for developers, think again. There is a place for you and every single contribution is important.

    Why bother?

    In 2013, Jay Balunas, the cofounder of AeroGear, a small open source project, saw that more than 85% of its Android code was written by a single developer: Daniel Passos. Jay had received some funding, so he reached out, offering him a job on the spot. But Daniel turned it down.

    Why would someone turn down a paid position and want to continue working for free? Passos lived thousands of miles away, in Rio de Janeiro. He also didn’t speak any English.

    Not about to lose a great developer that had already proven his worth, Jay solved the problem. He made the position remote, and sent an English teacher to Daniel’s house every week.

    This story may sound too good to be true. But this may describe the careers of more people than you think—people who did not start out contributing to open source ever expecting anything in return. They would probably describe their experience starting out as a labor of love.

    Getting a job offer shouldn’t be your only motivation to contribute to an open source project. If it is, you’ll likely be frustrated with the results.

    Working for free

    You may have a problem with working for free, especially when there seems to be plenty of well-paid work to go around. Why should you work in a vulnerable environment with total strangers, without ever receiving compensation?

    If you are in your early twenties, willing to work all night for the love of this industry, and have few pressing expenses, then building up your professional reputation on open source projects and sharing your ideas is a great thing to do. It’s how we all got started, how I and the majority of my peers found our voices.
    Rachel Andrew, “The High Price of Free

    On a professional level, among the biggest assets you have are your connections. But not everyone lives in a major tech industry area. Not everyone can attend industry conferences or participate in hackathons. The open source community opens a network of passionate and talented people from around the world. To become part of it, you don’t have to worry about whiteboarding exercises, interviews, or whether you have a degree from the right university.

    But you may be disappointed if you contribute to an open source project just to get a job. Open source is volunteer work, just like helping other not-for-profit and community organizations that need people in order to stay open and reach as many people as possible. It should be approached from a place of wanting to give back to your community and contributing to a worthy cause.

    Still, good employees are hard to find, and it’s often not a question of a person’s technical skills. Many companies today require applicants to participate in a months-long interview process, and complete hours of coding and design challenges that are unpaid, are unrecognized, and become the company’s property. In the case of Daniel Passos, by contributing to a project over time, he was able to demonstrate what he was capable of building, how he collaborated with others, and how passionate he was. This let him get past job requirements that aren’t related to the work but that are used to deny qualified job applicants all the time. This results in people who pay it forward: Daniel has since mentored many people in the community, including me.

    As a contributor, you will be able to experiment and play with bleeding-edge techniques at a scale that you would hardly find on a personal project or in a hackathon scenario. It’s also an opportunity to continue working with technologies that you might not get to use anymore in other work. And if you have been away from making things for a long time, an open source project is a great way to get back on track.

    Last but not least, it’s hard to explain with words the feeling you get when your name appears on a project. The positive feedback loop of being part of something larger than yourself is what makes open source addictive. Just ask what happened when a couple of people took over the blogging tool b2 when it was abandoned by its creator.

    Finding your community

    If all of this sounds good to you, it’s time to find your people. Start by taking a look at what you like and use. Ask yourself what problems you would like to solve. If you are passionate about something, there is probably a community around it.

    If you enjoy working with a particular technology, you have options spanning the entire programming realm. For example, if you are like me and enjoy working with CSS, you can contribute to projects like Bulma, Bootstrap, Tachyons, Tailwind CSS, or Foundation, or design systems like Primer, PatternFly, or Lightning, among many others. GitHub has a great open source explorer you can use to find a group.

    If you would like to work on use cases that you don’t get to in your day job, like healthcare software, for example, you can find lists of active projects by area and see what kind of contributions they need. OpenMRS is a great example of a project that benefits people outside the industry and that would never be successful with millions of developers but no designers, writers, or subject matter experts.

    Respect

    Brian Leathem, a notable open source developer, describes working on an open source project as being like working behind a glass wall. Every single action you take will be visible, transparent, and recorded. This makes you vulnerable, but a healthy community will make you feel welcome and comfortable. Check your project’s code of conduct before you contribute. Never tolerate harassment, bullying of any kind, or unkindness. If it happens and the members don’t act swiftly to enforce their code of conduct, they don’t deserve you.

    Communication

    Having said that, it’s essential to have a thick skin. Frame any criticism you will receive as a learning opportunity. When interacting with others, commit to setting aside ego for something bigger. Be humble, stay positive, have good arguments, and remain open-minded.

    Being able to connect with people who are very different from you will be critical. You may collaborate with someone from a part of the world where communication styles and customs are different. For example, some cultures expect you to be very assertive if you care deeply about something. This is very different than cultures where it’s impolite to disagree in an open forum.

    Trust

    As you take your first steps, you might notice that thriving open source communities are supported by people who trust each other. Learn to trust and to be trusted by showing what you are able to do, admitting when you are wrong or don’t know something, and letting people do their work. Approach your first contributions from a place of humility. Once you gain an understanding of how people like to work with one another, you will be able to make a bigger dent with bolder contributions.

    My very first contribution was to AeroGear, a small open source project. I downloaded the codebase to my computer, made my design changes, zipped the files, and sent an email to the community mailing list.

    To say that the community had trouble understanding the improvements I had made to the user experience would be an understatement. I felt terribly lost, and a little rejected. I really wanted to become a part of this open source project, but I didn’t know where to begin. So I asked for help, and the community had endless patience with me, even when I destroyed the repository a few times.

    The toolbox

    To participate in an open source project, you will need to shed any fears you may have of using the command line and working with version control. However, many open source projects are hosted on Github, where you might be able to avoid some of this if you do not code and are posting sketches, making changes to copy, or writing documentation.

    The command line

    Level Up Tutorials has a great video series about the command line if you are a visual learner. Their Command Line Basics #1 video is a good place to start. If you prefer to read, Remy Sharp’s Working the Command Line is excellent.

    Git

    For getting started with version control, GitHub has a great step-by-step guide to Git. There are many Git desktop apps like Sourcetree, GitHub Desktop, or GitKraken that will help you visualize what Git does. I still highly recommend becoming familiar with the Git command-line tool. It’s a steeper learning curve, but you’ll get a return on your investment.

    Communication channels

    Every community has its communication channels. There is almost always a mailing list where the most important decisions are made. GitHub’s Issues feature is used for contribution issue tracking. Forums are common for user discussions.

    Chat among contributors has traditionally been on IRC, but Slack, Rocket.Chat, and Gitter have become more popular, including for user discussions. Find out where your community hangs out, and get to know its members.

    Making your first contribution

    The harder part of getting started with open source is finding a community and becoming familiar with how it operates and communicates. If you have cleared that hurdle, you are more than ready to begin contributing. Start small, and be nice.

    Look at the issues for a small task you feel comfortable doing. On some projects they are tagged as “help wanted” or “good first issue.” Documentation is also a great place to start. Go through the “getting started” guides and see if they make sense to a newcomer, like you. Can you improve them, make them more clear? Look for a typo or a grammar mistake. Contributions like these are easy to merge and are a perfect starting point.

    If you want to contribute to a project in ways other than working on the code, these issues are good ways to introduce yourself and what you can do. For example, if you are a designer, a project will sometimes, but not always, be looking for UI designs. But in most cases, even on projects with very little UI, like a utility or a service, there will be usability problems that need solutions. By starting with pointing out unclear information and offering lots of quick solutions to a problem, you can start to demonstrate both your expertise and your passion.

    Sometimes, changes or further explanation will be requested. Other times you’ll break things, and that’s OK. I once sent a pull request that messed up the border radius of Bootstrap buttons. I hadn’t tested the result. Mark Otto, the leader of the project, took the time to write a comment explaining where I made a mistake and how I might fix it. He didn’t have to do that; I should have known better. The gesture and the respect for my time as a contributor made me want to help the project even more.

    Leveling up

    Here is a secret: you don’t need to make a ton of commits to become a top contributor. React is probably the most active open source project today, and to become a Top 100 React contributor, you only need to merge five commits. They can even be five typos that you’ve fixed in the docs! And you can make an even greater impact in smaller communities with that level of contribution.

    Commit to contribute

    If you value the idea of open source, you are worthy of contributing to a project, earning recognition, and being a respected member of a community. If you have different expertise, experience, or points of view about a project, we need you even more. At the end of the day, without people contributing to the community, the web will not remain open and free.

    Rachel Andrew goes on to write about how she’s seen people of her generation taking a step back, as she started to feel the pressure of the finite amount of time she has. Pioneers of the modern web like her paid it forward. Can you?

  • What is Typesetting?

    A note from the editors: We’re pleased to share an excerpt from Chapter 1 of Tim Brown’s Flexible Typesetting, from A Book Apart.

    Typesetting is the most important part of typography, because most text is meant to be read, and typesetting involves preparing text for reading.

    You’re already great at typesetting. Think about it. You choose good typefaces. You determine font sizes and line spacing. You decide on the margins that surround text elements. You set media query breakpoints. All of that is typesetting.

    Maybe you’re thinking, But Tim, I am a font muggins. Help me make better decisions! Relax. You make better decisions than you realize. Some people will try to make you feel inferior; ignore them. Your intuition is good. Practice, and your skills will improve. Make a few solid decisions; then build on them. I’ll help you get started.

    In this chapter, I’ll identify the value of typesetting and its place within the practice of typography. I’ll talk about pressure, a concept I use throughout this book to explain why typeset texts sometimes feel awkward or wrong. I’ll also discuss how typesetting for the web differs from traditional typesetting.

    Why does typesetting matter?

    Typesetting shows readers you care. If your work looks good and feels right, people will stick around—not only because the typography is comfortable and familiar, but also because you show your audience respect by giving their experience your serious attention (Fig 1.1).

    Two panels. On the left, text is small an unbalanced. On the right, the text is larger with proportional spacing.
    Fig 1.1: Glance at these two screenshots. Which one would you rather read? Which publisher do you think cares more about your experience?

    Sure, you could buy the “it” font of the moment (you know, the font all the cool people are talking about). You could use a template that promises good typography. You could use a script that spiffs up small typographic details. None of these things is necessarily bad in and of itself.

    But when you take shortcuts, you miss opportunities to care about your readers, the text in your charge, and the practice of typography, all of which are worthwhile investments. Spending time on these things can feel overwhelming, but the more you do it, the easier and more fun it becomes. And you can avoid feeling overwhelmed by focusing on the jobs type does.

    Imagine yourself in a peaceful garden. You feel the soft sun on your arms, and take a deep breath of fresh, clean air. The smell of flowers makes you feel happy. You hear honeybees hard at work, water trickling in a nearby brook, and birds singing. Now imagine that this garden needs a website, and you’re trying to find the right typeface.

    Sorry to spoil the moment! But hey, if you do this right, the website could give people the same amazing feeling as sitting in the garden itself.

    If you’re anything like me, your first instinct will be to recall sensations from the imaginary garden and look for a typeface with shapes that evoke similar sensations. But this is not a good way to choose among thousands upon thousands of fonts, because it’s too easy to end up with typefaces that—as charming as they may seem at first—don’t do their jobs. You’ll get disappointed and go right back to relying on shortcuts.

    Finding typefaces that are appropriate for a project, and that evoke the right mood, is easier and more effective if you know they’re good at the jobs you need them to do. The trick is to eliminate type that won’t do the job well (Fig 1.2).

    The Hatch font used as both heading and body copy. The body copy is awkward to read.
    Fig 1.2: Hatch, a typeface by Mark Caneso, is fun to use large, but not a good choice for body text.

    Depending on the job, some typefaces work better than others—and some don’t work well at all. Detailed, ornate type is not the best choice for body text, just as traditional text typefaces are not great for signage and user interfaces. Sleek, geometric fonts can make small text hard to read. I’ll come back to this at the beginning of Chapter 3.

    Considering these different jobs helps you make better design decisions, whether you’re selecting typefaces, tending to typographic details, or making text and layout feel balanced. We’ll do all of that in this book.

    Typesetting covers type’s most important jobs

    Typesetting, or the act of setting type, consists of typographic jobs that form the backbone of a reading experience: body text (paragraphs, lists, subheads) and small text (such as captions and asides). These are type’s most important jobs. The other parts of typography—which I call arranging and calibrating type—exist to bring people to the typeset text, so they can read and gather information (Fig 1.3).

    Illustrated typographic activities arranged in a pie chart, aligned with the jobs of setting, aligning, and calibrating text.
    Fig 1.3: Think of these typographic activities as job categories. In Chapter 3, we’ll identify the text blocks in our example project and the jobs they need to do.

    Let’s go over these categories of typographic jobs one by one. Setting type well makes it easy for people to read and comprehend textual information. It covers jobs like paragraphs, subheads, lists, and captions. Arranging type turns visitors and passersby into readers, by catching their attention in an expressive, visual way. It’s for jobs like large headlines, titles, calls to action, and “hero” areas. Calibrating type helps people scan and process complicated information, and find their way, by being clear and organized. This is for jobs like tabular data, navigation systems, infographics, math, and code.

    Arranging and calibrating type, and the jobs they facilitate, are extremely important, but I won’t spend much time discussing them in this book except to put them in context and explain where in my process I usually give them attention. They deserve their own dedicated texts. This book focuses specifically on setting type, for several reasons.

    First, typesetting is critical to the success of our projects. Although the decisions we make while typesetting are subtle almost to the point of being unnoticeable, they add up to give readers a gut feeling about the work. Typesetting lays a strong foundation for everything else.

    It also happens to be more difficult than other parts of typography. Good type for typesetting is harder to find than good type for other activities. Good typesetting decisions are harder to make than decisions about arranging type or calibrating type.

    Furthermore, typesetting can help us deeply understand the web’s inherent flexibility, which responsive web design has called attention to so well. The main reason I make a distinction between typesetting, arranging type, and calibrating type is because these different activities each require text to flex in different ways.

    In sum, typesetting matters because it is critical for readers, it supports other typographic activities, the difficult decisions informing it take practice, and its nature can help us understand flexibility and responsiveness on the web. A command of typesetting makes us better designers.

    Why do some websites feel wrong?

    It’s not hard to find websites that just feel, well, sort of wrong. They’re everywhere. The type they use is not good, the font size is too small (or too big), lines of text are too long (or comically short), line spacing is too loose or too tight, margins are either too small or way too big, and so on (Fig 1.4).

    Two panels. Text in the left panel is smaller with more vertical space between lines than the text in the right panel.
    Fig 1.4: Some typesetting just looks wrong. Why? Keep reading.

    It’s logical to think that websites feel wrong because, somewhere along the line, a typographer made bad decisions. Remember that a type designer is someone who makes type; a typographer is someone who uses type to communicate. In that sense, we are all typographers, even if we think of what we do as designing, or developing, or editing.

    For more than 500 years, the job of a typographer has been to decide how text works and looks, and over those years, typographers have made some beautiful stuff. So if some websites feel wrong, it must be because the typographers who worked on them were inexperienced, or lazy, or had no regard for typographic history. Right?

    Except that even the best typographers, who have years of experience, who have chosen a good typeface for the job at hand, who have made great typesetting decisions, who work hard and respect tradition—even those people can produce websites that feel wrong. Websites just seem to look awful in one way or another, and it’s hard to say why. Something’s just not quite right. In all likelihood, it’s the typesetting. Specifically, websites feel wrong when they put pressure on typographic relationships.

    Typographic relationships

    Have you ever chosen a new font for your blog template, or an existing project, and instinctively adjusted the font size or line spacing to make it feel better?

    Three panels (from left): Text set in Libre Franklin, the same text re-rendered in Kepler, and (finally) adjusted in Kepler.
    Fig 1.5: Replacing this theme’s default font with Kepler made the text seem too small. Size and line-spacing adjustments felt necessary

    Those typesetting adjustments help because the typeface itself, as well as its font size, measure (a typographic term for the length of lines of text), and line spacing all work together to make a text block feel balanced. (We’ll return to text blocks in more detail in Chapter 3.) This balance is something we all instinctively notice; when it’s disrupted, we sense pressure.

    But let’s continue for a moment with this example of choosing a new font. We sense pressure every time we choose a new font. Why? Because each typeface is sized and positioned in unique ways by its designer (Fig 1.6).

    Three panels (from left): “R” in Libre Franklin, Kepler at 100%, and Kepler height-adjusted to match Libre Franklin at 116%.
    Fig 1.6: Glyphs are sized and positioned within a font’s em box. When we set a font size, we are sizing the em box—not the glyph inside it.

    In Chapter 2, we’ll take a closer look at glyphs, which are instances of one or more characters. For now, suffice it to say that glyphs live within a bounding box called the em box, which is a built-in part of a font file. Type designers decide how big, small, narrow, or wide glyphs are, and where they are positioned, within this box. The em box is what becomes our CSS-specified font size—it maps to the CSS content area.

    So when we select a new typeface, the visible font size of our text block—the chunk of text to which we are applying styles— often changes, throwing off its balance. This means we need to carefully adjust the font size and then the measure, which depends on both the typeface and the font size. Finally, we adjust line spacing, which depends on the typeface, font size, and measure. I’ll cover how to fine-tune all of these adjustments in Chapter 4.

    Making so many careful adjustments to one measly text block seems quite disruptive, doesn’t it? Especially because the finest typographic examples in history—the work we admire, the work that endures—commands a compositional balance. Composition, of course, refers to a work of art or design in its
    entirety. Every text block, every shape, every space in a composition relates to another. If one text block is off-kilter, the whole work suffers.

    I’m sure you can see where I’m headed with this. The web puts constant pressure on text blocks, easily disrupting their balance in myriad ways.

    Pressure

    There are no “correct” fonts, font sizes, measures, or line heights. But relationships among these aspects of a text block determine whether reading is easier or harder. Outside forces can apply pressure to a balanced, easy-to-read text block, making the typesetting feel wrong, and thus interfering with reading.

    We just discussed how choosing a new typeface introduces pressure. The same thing happens when our sites use local fonts that could be different for each reader, or when webfonts fail to load and our text is styled with fallback fonts. Typefaces are not interchangeable. When they change, they cause pressure that we have to work hard to relieve.

    We also experience pressure when the font size changes (Fig 1.7). Sometimes, when we’re designing sites, we increase font size to better fill large viewports—the viewing area on our screens—or decrease it to better fit small ones. Readers can even get involved, by increasing or decreasing font size themselves to make text more legible. When font size changes, we have to consider whether our typeface, measure, and line spacing are still appropriate.

    Two panels (from left): The original typographic design and the effect of an increased font size.
    Fig 1.7: Left: a balanced text block. Right: a larger font size causes pressure.

    Changes to the width of our text block also introduce pressure (Fig 1.8). When text blocks stretch across very wide screens, or are squeezed into very narrow viewports, the entire composition has to be reevaluated. We may find that our text blocks need new boundaries, or a different font size, or even a different typeface, to make sure they maintain a good internal balance—and feel right for the composition. (This may seem fuzzy right now, but it will become clearer in Chapters 5 and 6, I promise.)

    Two panels (from left): The original typographic design and the effect of a narrower display area.
    Fig 1.8: Left: a balanced text block. Right: a narrower measure causes pressure.

    We also experience pressure when we try to manage white space without considering the relationships in our text blocks (Fig 1.9). When we predetermine our line height with a baseline grid, or when we adjust the margins that surround text as if they were part of a container into which text is poured rather than an extension of the balance in the typesetting, we risk destroying relationships among compositional white spaces— not only the white spaces in text blocks (word spacing, line spacing), but also the smaller white spaces built into our typefaces. These relationships are at risk whenever a website flexes, whenever a new viewport size comes along.

    Two panels (from left): The original typographic design and the effect of looser line spacing.
    Fig 1.9: Left: a balanced text block. Right: looser line spacing causes pressure.

    Typesetting for the web can only be successful if it relieves inevitable pressures like these. The problem is that we can’t see all of the pressures we face, and we don’t yet have the means (the words, the tools) to address what we can see. Yet our natural response, based on centuries of typographic control, is to try to make better decisions.

    But on the web, that’s like trying to predict the weather. We can’t decide whether to wear a raincoat a year ahead of time. What we can do is get a raincoat and be ready to use it under certain conditions. Typographers are now in the business of making sure text has a raincoat. We can’t know when it’ll be needed, and we can’t force our text to wear it, but we can make recommendations based on conditional instructions.

    For the first time in hundreds of years, because of the web, the role of the typographer has changed. We no longer decide; we make suggestions. We no longer choose typefaces, font size, line length, line spacing, and margins; we prepare and instruct text to make those choices for itself. We no longer determine page shape and quality; we respond to our readers’ contexts and environments.

    These changes may seem like a weakness compared to the command we have always been able to exercise. But they are in fact an incredible strength, because they mean that typeset text has the potential to fit everyone just right. In theory, at least, the web is universal.

    The primary design principle underlying the web’s usefulness and growth is universality.
    Tim Berners-Lee

    We must now practice a universal typography that strives to work for everyone. To start, we need to acknowledge that typography is multidimensional, relative to each reader, and unequivocally optional.

    Read the rest of this chapter and more when you buy the book!

  • Fixing Variable Scope Issues with ECMAScript 6

    Variable scope has always been tricky in JavaScript, particularly when compared to more structured languages like C and Java. For years, there wasn’t much talk about it because we had few options for really changing it. But ECMAScript 6 introduced some new features to help give developers more control of variable scope. Browser support is pretty great and these features are ready to use for most developers today. But which to choose? And what, exactly, do they do?

    This article spells out what these new features are, why they matter, and how to use them. If you’re ready to take more control over variable scope in your projects or just want to learn the new way of doing things, read on.

    Variable scope: a quick primer

    Variable scope is an important concept in programming, but it can confuse some developers, especially those new to programming. Scope is the area in which a variable is known. Take a look at the following code:

    var myVar = 1;
    
    function setMyVar() {
      myVar = 2;
    }
    
    setMyVar();
    
    console.log(myVar);

    What does the console log read? Not surprisingly, it reads 2. The variable myVar is defined outside of any function, meaning it’s defined in the global scope. Consequently, every function here will know what myVar is. In fact, even functions in other files that are included on the same page will know what this variable is.

    Now consider the following code:

    function setMyVar() {
      var myVar = 2;
    }
    
    setMyVar();
    
    console.log(myVar);

    All we did was move where the variable was declared. So what does the console log read now? Well, it throws a ReferenceError because myVar is not defined. That’s because the var declaration here is function-level, making the scope extend only within the function (and any potential functions nested in it), but not beyond. If we want a variable’s scope to be shared by two or more functions on the same level, we need to define the variable one level higher than the functions.

    Here’s the tricky thing: most websites and apps don’t have all of the code written by one developer. Most will have several developers touching the code, as well as third-party libraries and frameworks thrown into the mix. And even if it’s just one developer, it’s common to pull JavaScript in from several places. Because of this, it’s generally considered bad practice to define a variable in the global scope—you never know what other variables other developers will be defining. There are some workarounds to share variables among a group of functions—most notably, the module pattern and IIFEs in object-oriented JavaScript, although encapsulating data and functions in any object will accomplish this. But variables with scopes larger than necessary are generally problematic.

    The problem with var

    Alright, so we’ve got a handle on variable scope. Let’s get into something more complex. Take a look at the following code:

    function varTest() {
      for (var i = 0; i < 3; i++) {
        console.log(i);
      }
      console.log(i);
    }
    
    varTest();

    What are the console logs? Well, inside the loop, you get the iteration variable as it increments: 0, 1, 2. After that, the loop ends and we move on. Now we try to reference that same variable outside of the for loop it was created in. What do we get?

    The console log reads 3 because the var statement is function-level. If you define a variable using var, the entire function will have access to it, no matter where it is defined in that function.

    This can get problematic when functions become more complex. Take a look at the following code:

    function doSomething() {
      var myVar = 1;
      if (true) {
        var myVar = 2;
        console.log(myVar);
      }
      console.log(myVar);
    }
    
    doSomething();

    What are the console logs? 2 and 2. We define a variable equal to 1, and then try to redefine the same variable inside the if statement. Since those two exist in the same scope, we can’t define a new variable, even though that’s obviously what we want, and the first variable we set is overwritten inside the if statement.

    That right there is the biggest shortcoming with var: its scope is too large, which can lead to unintentional overwriting of data, and other errors. Large scope often leads to sloppy coding as well—in general, a variable should only have as much scope as it needs and no more. What we need is a way to declare a variable with a more limited scope, allowing us to exercise more caution when we need to.

    Enter ECMAScript 6.

    New ways to declare variables

    ECMAScript 6 (a new set of features baked into JavaScript, also known as ES6 or ES2015) gives us two new ways to define variables with a more limited scope: let and const. Both give us block-level scope, meaning scope can be contained within blocks of code like for loops and if statements, giving us more flexibility in choosing how our variables are scoped. Let’s take a look at both.

    Using let

    The let statement is simple: it’s mostly like var, but with limited scope. Let’s revisit that code sample from above, replacing var with let:

    function doSomething() {
      let myVar = 1;
      if (true) {
        let myVar = 2;
        console.log(myVar);
      }
      console.log(myVar);
    }
    
    doSomething();

    In this case, the console logs would read 2 and 1. This is because an if statement defines a new scope for a variable declared with let—the second variable we declare is actually a separate entity than the first one, and we can set both independently. But that doesn’t mean that nested blocks like that if statement are completely cut off from higher-level scopes. Observe:

    function doSomething() {
      let myVar = 1;
      if (true) {
        console.log(myVar);
      }
    }
    
    doSomething();

    In this case, the console log would read 1. The if statement has access to the variable we created outside of it and is able to log that. But what happens if we try to mix scopes?

    function doSomething() {
      let myVar = 1;
      if (true) {
        console.log(myVar);
        let myVar = 2;
        console.log(myVar);
      }
    }
    
    doSomething();

    You might think that first console log would read 1, but it actually throws a ReferenceError, telling us that myVar is not defined or initialized for that scope. (The terminology varies across browsers.) JavaScript variables are hoisted in their scope—if you declare a variable within a scope, JavaScript reserves a place for it even before you declare it. How that variable is reserved differs between var and let.

    console.log(varTest);
    var varTest = 1;
    
    console.log(letTest);
    let letTest = 2;

    In both cases here, we’re trying to use a variable before it’s defined. But the console logs behave differently. The first one, using a variable later declared with var, will read undefined, which is an actual variable type. The second one, using a variable later defined with let, will throw a ReferenceError and tell us that we’re trying to use that variable before it’s defined/initialized. What’s going on?

    Before executing, JavaScript will do a quick read of the code and see if any variables will be defined, and hoist them within their scope if they are. Hoisting reserves that space, even if the variable exists in the parent scope. Variables declared with var will be auto-initialized to undefined within their scope, even if you reference them before they’re declared. The big problem is that undefined doesn’t always mean you’re using a variable before it’s defined. Look at the following code:

    var var1;
    console.log(var1);
    
    console.log(var2);
    var var2 = 1;

    In this case, both console logs read undefined, even though different things are happening. Variables that are declared with var but have no value will be assigned a value of undefined; but variables declared with var that are referenced within their scope before being declared will also return undefined. So if something goes wrong in our code, we have no indication which of these two things is happening.

    Variables defined with let are reserved in their block, but until they’re defined, they go into the Temporal Dead Zone (TDZ)—they can’t be used and will throw an error, but JavaScript knows exactly why and will tell you.

    let var1;
    console.log(var1);
    
    console.log(var2);
    let var2 = 1;

    In this case, the first console log reads undefined, but the second throws a ReferenceError, telling us the variable hasn’t been defined/initialized yet.

    So, using var, if we see undefined, we don’t know if the variable has been defined and just doesn’t have a value, or if it hasn’t been defined yet in that scope but will be. Using let, we get an indication of which of these things is happening—much more useful for debugging.

    Using const

    The const statement is very similar to let, but with one major exception: it does not allow you to change the value once initialized. (Some more complex types, like Object and Array, can be modified, but can’t be replaced. Primitive types, like Number and String, cannot change at all.) Take a look at the following code:

    let mutableVar = 1;
    const immutableVar = 2;
    
    mutableVar = 3;
    immutableVar = 4;

    That code will run fine until the last line, which throws a TypeError for assignment to a constant variable. Variables defined with const will throw this error almost any time you try to reassign one, although object mutation can cause some unexpected results.

    As a JavaScript developer, you might be wondering what the big deal is about immutable variables. Constant variables are new to JavaScript, but they’ve been a part of languages like C and Java for years. Why so popular? They make us think about how our code is working. There are some cases where changing a variable can be harmful to the code, like when doing calculations with pi or when you have to reference a certain HTML element over and over:

    const myButton = document.querySelector('#my-button');

    If our code depends on that reference to that specific HTML element, we should make sure it can’t be reassigned.

    But the case for const goes beyond that. Remember our best practice of only giving variables the scope they need and no more. In that same line of thought, we should only give variables the mutability they need and no more. Zell Liew has written much more on the subject of immutable variables, but the bottom line is that making variables immutable makes us think more about our code and leads to cleaner code and fewer surprises.

    When I was first starting to use let and const, my default option was let, and I would use const only if reassignment would cause harm to the code. But after learning more about programming practices, I changed my mind on this. Now, my default option is const, and I use let only if reassignment is necessary. That forces me to ask if reassignment for a variable is really necessary—most of the time, it’s not.

    Is there a case for var?

    Since let and const allow for more careful coding, is there a case for var anymore? Well, yes. There are a few cases where you’d want to use var over the new syntax. Give these careful consideration before switching over to the new declarations.

    Variables for the masses

    Variables declared with var do have one thing that the others don’t, and it’s a big one: universal browser support. 100% of browsers support var. Support is pretty great for both let and const, but you have to consider how differently browsers handle JavaScript it doesn’t understand vs. CSS it doesn’t understand.

    If a browser doesn’t support a CSS feature, most of the time that’s just going to mean a display bug. Your site may not look the same as in a supporting browser, but it’s most likely still usable. If you use let and a browser doesn’t support it, that JavaScript will not work. At all. With JavaScript being such an integral part of the web today, that can be a major problem if you’re aiming to support old browsers in any way.

    Most support conversations pose the question, “What browsers do we want to deliver an optimal experience for?” When you’re dealing with a site containing core functionality that relies on let and const, you’re essentially asking the question, “What browsers do we want to ban from using our site?” This should be a different conversation than deciding whether you can use display: flex. For most websites, there won’t be enough users of non-supporting browsers to worry about. But for major revenue-generating sites or sites where you’re paying for traffic, this can be a serious consideration. Make sure that risk is alright with your team before proceeding.

    If you need to support really old browsers but want to use let and const (and other new, ES6 constructs), one solution is to use a JavaScript transpiler like Babel to take care of this for you. With Babel, you can write modern JavaScript with new features and then compile it into code that’s supported by older browsers.

    Sound too good to be true? Well, there are some caveats. The resulting code is much more verbose than you’d write on your own, so you end up with a much larger file than necessary. Also, once you commit to a transpiler, that codebase is going to be stuck with that solution for a while. Even if you’re writing valid ECMAScript 6 for Babel, dropping Babel later will mean testing your code all over again, and that’s a hard sell for any project team when you have a version that’s working perfectly already. When’s the next time you’re going to rework that codebase? And when is that IE8 support not going to matter anymore? It might still be the best solution for the project, but make sure you’re comparing those two timelines.

    And for the next trick ...

    There is one more thing var can do that the others can’t. This is a niche case, but let’s say you have a situation like this:

    var myVar = 1;
    
    function myFunction() {
      var myVar = 2;
      // Oops! We need to reference the original myVar!
    }

    So we defined myVar in the global scope, but later lost that reference because we defined it in a function, yet we need to reference the original variable. This might seem silly, because you can ordinarily just pass the first variable into the function or rename one of them, but there may be some situations where your level of control over the code prevents this. Well, var can do something about that. Check it out:

    var myVar = 1;
    
    function myFunction() {
      var myVar = 2;
      console.log(myVar); // 2
      console.log(window.myVar); // 1
    }

    When a variable is defined on the global scope using var, it automatically attaches itself to the global window object—something let and const don’t do. This feature helped me out once in a situation where a build script validated JavaScript before concatenating files together, so a reference to a global variable in another file (that would soon be concatenated into the same file upon compilation) threw an error and prevented compilation.

    That said, relying on this feature often leads to sloppy coding. This problem is most often solved with greater clarity and smaller margin of error by attaching variables to your own object:

    let myGlobalVars = {};
    let myVar = 1;
    myGlobalVars.myVar = myVar;
    
    function myFunction() {
      let myVar = 2;
      console.log(myVar); // 2
      console.log(myGlobalVars.myVar); // 1
    }

    Yes, this requires an extra step, but it reduces confusion in working around something you’re not really supposed to be doing anyway. Nonetheless, there may be times when this feature of var is useful. Try to find a cleaner workaround before resorting to this one, though.

    Which do I use?

    So how do you choose? What’s the priority for using these? Here’s the bottom line.

    First question: are you supporting IE10 or really old versions of other browsers in any way? If the answer is yes, and you don’t want to go with a transpiler solution, you need to choose var.

    If you’re free to use the features that are new in ES6, start by making every variable a const. If a variable needs to be reassigned (and try to write your code so it doesn’t), switch it to let.

    Scoping for the future

    ECMAScript 6 statements like let and const give us more options for controlling variable scope in our websites and apps. They make us think about what our code is doing, and support is great. Give it careful consideration, of course, but coding with these declarations will make your codebase more stable and prepare it for the future.

  • Webmentions: Enabling Better Communication on the Internet

    Over 1 million Webmentions will have been sent across the internet since the specification was made a full Recommendation by the W3C—the standards body that guides the direction of the web—in early January 2017. That number is rising rapidly, and in the last few weeks I’ve seen a growing volume of chatter on social media and the blogosphere about these new “mentions” and the people implementing them.

    So what are Webmentions and why should we care?

    While the technical specification published by the W3C may seem incomprehensible to most, it’s actually a straightforward and extremely useful concept with a relatively simple implementation. Webmentions help to break down some of the artificial walls being built within the internet and so help create a more open and decentralized web. There is also an expanding list of major web platforms already supporting Webmentions either natively or with easy-to-use plugins (more on this later).

    Put simply, Webmention is a (now) standardized protocol that enables one website address (URL) to notify another website address that the former contains a reference to the latter. It also allows the latter to verify the authenticity of the reference and include its own corresponding reference in a reciprocal way. In order to understand what a big step forward this is, a little history is needed.

    The rise of @mentions

    By now most people are familiar with the ubiquitous use of the “@” symbol in front of a username, which originated on Twitter and became known as @mentions and @replies (read “at mentions” and “at replies”). For the vast majority, this is the way that one user communicates with other users on the platform, and over the past decade these @mentions, with their corresponding notification to the receiver, have become a relatively standard way of communicating on the internet.

    Tweet from Wiz Khalifa: 'I been smashed the idea of that album even existing. I got joints to roll @kanyewest'
    Tweet from Wiz Khalifa

    Many other services also use this type of internal notification to indicate to other users that they have been referenced directly or tagged in a post or photograph. Facebook allows it, so does Instagram. Google+ has a variant that uses + instead of @, and even the long-form article platform Medium, whose founder Ev Williams also co-founded Twitter, quickly joined the @mentions party.

    The biggest communications problem on the internet

    If you use Twitter, your friend Alice only uses Facebook, your friend Bob only uses his blog on WordPress, and your pal Chuck is over on Medium, it’s impossible for any one of you to @mention another. You’re all on different and competing platforms, none of which interoperate to send these mentions or notifications of them. The only way to communicate in this way is if you all join the same social media platforms, resulting in the average person being signed up to multiple services just to stay in touch with all their friends and acquaintances.

    Given the issues of privacy and identity protection, different use cases, the burden of additional usernames and passwords, and the time involved, many people don’t want to do this. Possibly worst of all, your personal identity on the internet can end up fragmented like a Horcrux across multiple websites over which you have little, if any, control.

    Imagine if AT&T customers could only speak to other AT&T customers and needed a separate phone, account, and phone number to speak to friends and family on Verizon. And still another to talk to friends on Sprint or T-Mobile. The massive benefit of the telephone system is that if you have a telephone and service (from any one of hundreds or even thousands of providers worldwide), you can potentially reach anyone else using the network. Surely, with a basic architecture based on simple standards, links, and interconnections, the same should apply to the internet?

    The solution? Enter Webmentions!

    As mentioned earlier, Webmentions allow notifications between web addresses. If both sites are set up to send and receive them, the system works like this:

    1. Alice has a website where she writes an article about her rocket engine hobby.
    2. Bob has his own website where he writes a reply to Alice’s article. Within his reply, Bob includes the permalink URL of Alice’s article.
    3. When Bob publishes his reply, his publishing software automatically notifies Alice’s server that her post has been linked to by the URL of Bob’s reply.
    4. Alice’s publishing software verifies that Bob’s post actually contains a link to her post and then (optionally) includes information about Bob’s post on her site; for example, displaying it as a comment.

    A Webmention is simply an @mention that works from one website to another!

    If she chooses, Alice can include the full text of Bob’s reply—along with his name, photo, and his article’s URL (presuming he’s made these available)—as a comment on her original post. Any new readers of Alice’s article can then see Bob’s reply underneath it. Each can carry on a full conversation from their own websites and in both cases display (if they wish) the full context and content.

    Diagram showing comments sections on two different websites, carrying on a single conversation
    Using Webmentions, both sides can carry on a conversation where each is able to own a copy of the content and provide richer context.

    User behaviors with Webmentions are a little different than they are with @mentions on Twitter and the like in that they work between websites in addition to within a particular website. They enable authors (of both the original content and the responses) to own the content, allowing them to keep a record on the web page where it originated, whether that’s a website they own or the third-party platform from which they chose to send it.

    Interaction examples with Webmention

    Webmentions certainly aren’t limited to creating or displaying “traditional” comments or replies. With the use of simple semantic microformats classes and a variety of parsers written in numerous languages, one can explicitly post bookmarks, likes, favorites, RSVPs, check-ins, listens, follows, reads, reviews, issues, edits, and even purchases. The result? Richer connections and interactions with other content on the web and a genuine two-way conversation instead of a mass of unidirectional links. We’ll take a look at some examples, but you can find more on the IndieWeb wiki page for Webmention alongside some other useful resources.

    Marginalia

    With Webmention support, one could architect a site to allow inline marginalia and highlighting similar to Medium.com’s relatively well-known functionality. With the clever use of URL fragments, which are well supported in major browsers, there are already examples of people who use Webmentions to display word-, sentence-, or paragraph-level marginalia on their sites. After all, aren’t inline annotations just a more targeted version of comments?

    Screenshot of an article with a response off to the side
    An inline annotation on the post “Hey Ev, what about mentions?,” in which Medium began to roll out their @mention functionality.

    Reads

    As another example, and something that could profoundly impact the online news business, I might post a link on my website indicating I’ve read a particular article on, say, The New York Times. My site sends a “read” Webmention to the article, where a facepile or counter showing the number of read Webmentions received could be implemented. Because of the simplified two-way link between the two web pages, there is now auditable proof of interaction with the content. This could similarly work with microinteractions such as likes, favorites, bookmarks, and reposts, resulting in a clearer representation of the particular types of interaction a piece of content has received. Compared to an array of nebulous social media mini-badges that provide only basic counters, this is a potentially more valuable indicator of a post’s popularity, reach, and ultimate impact.

    Listens

    Building on the idea of using reads, one could extend Webmentions to the podcasting or online music sectors. Many platforms are reasonably good at providing download numbers for podcasts, but it is far more difficult to track the number of actual listens. This can have a profound effect on the advertising market that supports many podcasts. People can post about what they’re actively listening to (either on their personal websites or via podcast apps that could report the percentage of the episode listened to) and send “listen” Webmentions to pages for podcasts or other audio content. These could then be aggregated for demographics on the back end or even shown on the particular episode’s page as social proof of the podcast’s popularity.

    For additional fun, podcasters or musicians might use Webmentions in conjunction with media fragments and audio or video content to add timecode-specific, inline comments to audio/video players to create an open standards version of SoundCloud-like annotations and commenting.

    Screenshot of a Soundcloud audio file with little icons scatter about the timeline
    SoundCloud allows users to insert inline comments that dovetail with specific portions of audio.

    Reviews

    Websites selling products or services could also accept review-based Webmentions that include star-based ratings scales as well as written comments with photos, audio, or even video. Because Webmentions are a two-way protocol, the reverse link to the original provides an auditable path to the reviewer and the opportunity to assess how trustworthy their review may be. Of course, third-party trusted sites might also accept these reviews, so that the receiving sites can’t easily cherry-pick only positive reviews for display. And because the Webmention specification includes the functionality for editing or deletion, the original author has the option to update or remove their reviews at any time.

    Getting started with Webmentions

    Extant platforms with support

    While the specification has only recently become a broad recommendation for use on the internet, there are already an actively growing number of content management systems (CMSs) and platforms that support Webmentions, either natively or with plugins. The simplest option, requiring almost no work, is a relatively new and excellent social media service called Micro.blog, which handles Webmentions out of the box. CMSs like Known and Perch also have Webmention functionality built in. Download and set up the open source software and you’re ready to go.

    If you’re working with WordPress, there’s a simple Webmention plugin that will allow you to begin using Webmentions—just download and activate it. (For additional functionality when displaying Webmentions, there’s also the recommended Semantic Linkbacks plugin.) Other CMSs like Drupal, ProcessWire, Elgg, Nucleus CMS, Craft, Django, and Kirby also have plugins that support the standard. A wide variety of static site generators, like Hugo and Jekyll, have solutions for Webmention technology as well. More are certainly coming.

    If you can compose basic HTML on your website, Aaron Parecki has written an excellent primer on “Sending Your First Webmention from Scratch.”

    A weak form of Webmention support can be bootstrapped for Tumblr, WordPress.com, Blogger, and Medium with help from the free Bridgy service, but the user interface and display would obviously be better if they were supported fully and natively.

    As a last resort, if you’re using Tumblr, WordPress.com, Wix, Squarespace, Ghost, Joomla, Magento, or any of the other systems without Webmention, file tickets asking them to support the standard. It only takes a few days of work for a reasonably experienced developer to build support, and it substantially improves the value of the platform for its users. It also makes them first-class decentralized internet citizens.

    Webmentions for developers

    If you’re a developer or a company able to hire a developer, it is relatively straightforward to build Webmentions into your CMS or project, even potentially open-sourcing the solution as a plugin for others. For anyone familiar with the old specifications for pingback or trackback, you can think of Webmentions as a major iteration of those systems, but with easier implementation and testing, improved performance and display capabilities, and decreased spam vulnerabilities. Because the specification supports editing and deleting Webmentions, it provides individuals with more direct control of their data, which is important in light of new laws like GDPR.

    In addition to reading the specification, as mentioned previously, there are multiple open source implementations already written in a variety of languages that you can use directly, or as examples. There are also a test suite and pre-built services like Webmention.io, Telegraph, mention-tech, and webmention.herokuapp.com that can be quickly leveraged.

    Maybe your company allows employees to spend 20% of their time on non-specific projects, as Google does. If so, I’d encourage you to take the opportunity to fbuild Webmentions support for one or more platforms—let’s spread the love and democratize communication on the web as fast as we can!

    And if you already have a major social platform but don’t want to completely open up to sending and receiving Webmentions, consider using Webmention functionality as a simple post API. I could easily see services like Twitter, Mastodon, or Google+ supporting the receiving of Webmentions, combined with a simple parsing mechanism to allow Webmention senders to publish syndicated content on their platform. There are already several services like IndieNews, with Hacker News-like functionality, that allow posting to them via Webmention.

    If you have problems or questions, I’d recommend joining the IndieWeb chat room online via IRC, web interface, Slack, or Matrix to gain access to further hints, pointers, and resources for implementing a particular Webmention solution.

    The expansion of Webmentions

    The big question many will now have is Will the traditional social media walled gardens like Facebook, Twitter, Instagram, and the like support the Webmention specification?

    At present, they don’t, and many may never do so. After all, locking you into their services is enabling them to leverage your content and your interactions to generate income. However, I suspect that if one of the major social platforms enabled sending/receiving Webmentions, it would dramatically disrupt the entire social space.

    In the meantime, if your site already has Webmentions enabled, then congratulations on joining the next revolution in web communication! Just make sure you advertise the fact by using a button or badge. You can download a copy here.

  • Order Out of Chaos: Patterns of Organization for Writing on the Job

    A few years ago, a former boss of mine emailed me out of the blue and asked for a resource that would help him and his colleagues organize information more effectively. Like a dutiful friend, I sent him links to a few articles and the names of some professional writing books. And I qualified my answer with that dreaded disclaimer: “Advice varies widely depending on the situation.” Implication: “You’ll just have to figure out what works best for you. So, good luck!”

    In retrospect, I could have given him a better answer. Much like the gestalt principles of design that underpin so much of what designers do, there are foundational principles and patterns of organization that are relevant to any professional who must convey technical information in writing, and you can adapt these concepts to bring order out of chaos whether or not you’re a full-time writer.

    Recognize the primary goals: comprehension and performance

    Not long after I wrote my response, I revisited a book I’d read in college: Technical Editing, by Carolyn D. Rude. In my role as a technical writer, I reference the book every now and then for practical advice on revising software documentation. This time, as I reviewed the chapter on organization, I realized that Rude explained the high-level goals and principles better than any other author I’d read up to that point.

    In short, she says that whether you are outlining a procedure, describing a product, or announcing a cool new feature, a huge amount of writing in the workplace is aimed at comprehension (here’s what X is and why you should care) and performance (here’s how to do X). She then suggests that editors choose from two broad kinds of order to support these goals: content-based order and task-based order. The first refers to structures that guide readers from major sections to more detailed sections to facilitate top-down learning; the second refers to structures of actions that readers need to carry out. Content-based orders typically start with nouns, whereas task-based orders typically begin with verbs.

    Content-Based Order Example

    Product Overview

    • Introduction
    • Features
      • Feature 1
      • Feature 2
      • Feature n
    • Contact
    • Support

    Task-Based Order Example

    User Guide (WordPress)

    • Update your title and tagline
    • Pick a theme you love
    • Add a header or background
    • Add a site icon
    • Add a widget

    Of course, not all writing situations fall neatly into these buckets. If you were to visit Atlassian’s online help content, you would see a hybrid of content-based topics at the first level and task-based topics within them. The point is that as you begin to think about your organization, you should ask yourself:

    • Which of the major goals of organization (comprehension or performance) am I trying to achieve?
    • And which broad kind of order will help me best achieve those goals?

    This is still pretty abstract, so let’s consider the other principles from Carolyn Rude, but with a focus on how a writer rather than an editor should approach the task of organization.1

    Steal like an organizer: follow pre-established document structures

    In his book Steal Like an Artist, Austin Kleon argues that smart artists don’t actually create anything new but rather collect inspiring ideas from specific role models, and produce work that is profoundly shaped by them.

    “If we’re free from the burden of trying to be completely original,” he writes, “we can stop trying to make something out of nothing, and we can embrace influence instead of running away from it.”

    The same principle applies to the art of organization. To “steal like an organizer” means to look at what other people have written and to identify and follow pre-established structures that may apply to your situation. Doing so not only saves time and effort but also forces you to remember that your audience may already expect a particular pattern—and experience cognitive dissonance if they don’t get it.

    You are probably familiar with more pre-established structures than you think. News reports follow the inverted pyramid. Research reports often adhere to some form of the IMRAD structure (Introduction, Methodology, Results, and Discussion). Instruction manuals typically have an introductory section followed by tasks grouped according to the typical sequence a user would need to follow. Even troubleshooting articles tend to have a standard structure of Problem, Cause, and Solution.

    All this may sound like common sense, and yet many writers entirely skip this process of adapting pre-made structures. I can understand the impulse. When you face a blank screen, it feels simpler to capture the raw notes and organize it all later. That approach can certainly help you get into the flow, but it may also result in an ad hoc structure that fails to serve readers who are less familiar with your material.

    Instead, when you begin the writing process, start by researching available templates or pre-made structures that could support your situation. Standard word processors and content management systems already contain some good templates, and it’s easy to search for others online. Your fellow writers and designers are also good resources. If you’re contributing to a series of documents at your organization, you should get familiar with the structure of that series and learn how to work within it. Or you can do some benchmarking and steal some ideas from how other companies structure similar content.

    My team once had to do our own stealing for a major project that affected about half our company. We needed to come up with a repeatable structure for standard operating procedures (SOPs) that any employee could use to document a set of tasks. Knowing SOPs to be a well-established genre, we found several recommended structures online and in books, and came up with a list of common elements. We then decided which ones to steal and arranged them into a sequence that best suited our audience. We made out like bandits.

    Structural SOP Elements We Found Our Assessment
    Overview Steal
    Roles Involved Steal
    Dependencies Steal
    Estimated Level of Effort Nah, too hard to calculate and maintain.
    Process Diagram Meh, kind of redundant, not to mention a lot of work. No thanks.
    Tasks Steal
    Task n Steal
    Task n Introduction Steal
    Task n Responsibility Steal
    Task n Steps Steal
    See Also Steal

    But what if there is no pre-established pattern? Or what if a pattern exists, but it’s either too simple or too complex for what you’re trying to accomplish? Or what if it’s not as user-friendly as you would like?

    There may indeed be cases where you need to develop a mostly customized structure, which can be daunting. But fear not! That’s where the other principles of organization come in.

    Anticipate your readers’ questions (and maybe even talk to them)

    Recently I had an extremely frustrating user experience. While consulting some documentation to learn about a new process, I encountered a series of web pages that gave no introduction and dove straight into undefined jargon and acronyms that I had never heard of. When I visited related pages to get more context, I found the same problem. There was no background information for a newbie like me. The writers failed in this case to anticipate my questions and instead assumed a great deal of prior knowledge.

    Don’t make this mistake when you design your structure. Like a journalist, you need to answer the who, what, where, when, how, and why of your content, and then incorporate the answers in your structure. Anticipate common questions, such as “What is this? Where do I start? What must I know? What must I do?” This sort of critical reflection is all the more important when organizing web content, because users will almost certainly enter and exit your pages in nonlinear, unpredictable ways.

    If possible, you should also meet with your readers, and gather information about what would best serve them. One simple technique you could try is to create a knowledge map, an annotated matrix of sorts that my team once built after asking various teams about their information priorities. On the left axis, we listed categories of information that we thought each team needed. Along the top axis, we listed a column for each team. We then gave team representatives a chance to rank each category and add custom categories we hadn’t included. (You can learn more about the process we followed in this video presentation.)

    A screenshot of a knowledge map my team created after asking other teams which categories of information were most important to them.
    A knowledge map my team created after asking other teams which categories of information were most important to them.

    The weakness of this approach is that it doesn’t reveal information that your audience doesn’t know how to articulate. To fill in this gap, I recommend running a few informal usability tests. But if you don’t have the time for that, building a knowledge map is better than not meeting with your readers at all, because it will help you discover structural ideas you hadn’t considered. Our knowledge map revealed multiple categories that were required across almost all teams—which, in turn, suggested a particular hierarchy and sequence to weave into our design.

    Go from general to specific, familiar to new

    People tend to learn and digest information best by going from general to specific, and familiar to new. By remembering this principle, which is articulated in the schema theory of learning, you can better conceptualize the structure you’re building. What are the foundational concepts of your content? They should appear in your introductory sections. What are the umbrella categories under which more detailed categories fall? The answer should determine which headings belong at the top and subordinate levels of your hierarchy. What you want to avoid is presenting new ideas that don’t flow logically from the foundational concepts and expectations that your readers bring to the table.

    Consider the wikiHow article “How to Create a Dungeons and Dragons Character.” It begins by defining what Dungeons and Dragons is and explaining why you need to create a character before you can start playing the game.

    A screenshot of Part 1 of the wikiHow article “How to Create a Dungeons and Dragons Character,” which helps readers learn by starting with general concepts before moving on to specifics.
    Writers at wikiHow help readers learn by starting with general concepts before moving on to specifics.

    The next section, “Part 1: Establishing the Basics,” guides the reader into subsequent foundational steps, such as deciding which version of the game to follow and printing out a character sheet. Later sections (“Selecting a gender and race,” “Choosing a class,” and “Calculating ability scores”) expand on these concepts to introduce more specific, unfamiliar ideas in an incremental fashion, leading readers up a gentle ramp into new territory.

    Use conventional patterns to match structure to meaning

    Within the general-to-specific/familiar-to-new framework, you can apply additional patterns of organization that virtually all humans understand. Whereas the pre-established document structures above are usually constructed for particular use cases or genres, other conventional patterns match more general mental models (or “schemas,” as the schema theory so elegantly puts it) that we use to make sense of the world. These patterns include chronological, spatial, comparison-contrast, cause-effect, and order of importance.

    Chronological

    The chronological pattern reveals time or sequence. It’s appropriate for things like instructions, process flows, progress reports, and checklists. In the case of instructions, the order of tasks on a page often implies (or explicitly states) the “proper” or most common sequence for a user to follow. The wikiHow article above, for example, offers a recommended sequence of tasks for beginner players. In the case of progress reports, the sections may be ordered according to the periods of time in which work was done, as in this sample outline from the book Reporting Technical Information, by Kenneth W. Houp et al.:

    Beginning

    • Introduction
    • Summary of work completed

    Middle

    • Work completed
      • Period 1 (beginning and end dates)
        • Description
        • Cost
      • Period 2 (beginning and end dates)

        • Description
        • Cost
    • Work remaining

      • Period 3 (or remaining periods)
        • Description of work to be done
        • Expected cost

    End

    • Evaluation of work in this period
    • Conclusions and recommendations

    The principles of organization listed in this article are in fact another example of the chronological pattern. As Carolyn Rude points out in her book, the principles are arranged as a sort of methodology to follow. Try starting at the top of the list and work your way down. You may find it to be a useful way to produce order out of the chaos before you.

    Spatial

    The spatial pattern refers to top-to-bottom, left-to-right structures of organization. This is a good pattern if you need to describe the components of an interface or a physical object.

    Take a look at the neighbor comparison graph below, which is derived from a sample energy efficiency solution offered by Oracle Utilities. Customers who see this graph would most likely view it from top to bottom and left to right.

    A neighbor comparison graph that shows a customer how they compare with their neighbors in terms of energy efficiency.
    A neighbor comparison graph that shows a customer how they compare with their neighbors in terms of energy efficiency.

    A detailed description of this feature would then describe each component in that same order. Here’s a sample outline:

    • Feature name
      • Title
      • Bar chart
        • Efficient neighbors
        • You
        • Average neighbors
      • Date range
      • Performance insight

        • Great
        • Good
        • Using more than average
      • Energy use insight
      • Comparison details (“You’re compared with 10 homes within 6 miles …”)

    Comparison-contrast

    The comparison-contrast pattern helps users weigh options. It’s useful when reporting the pros and cons of different decisions or comparing the attributes of two or more products or features. You see it often when you shop online and need to compare features and prices. It’s also a common pattern for feasibility studies or investigations that list options along with upsides and downsides.

    Cause-effect

    The cause-effect pattern shows relationships between actions and reactions. Writers often use it for things like troubleshooting articles, medical diagnoses, retrospectives, and root cause analyses. You can move from effect to cause, or cause to effect, but you should stick to one direction and use it consistently. For example, the cold and flu pages at Drugs.com follow a standard cause-effect pattern that incorporates logical follow-up sections such as “Prevention” and “Treatment”:

    • What Is It? (This section defines the illness and describes possible “causes.”)
    • Symptoms (This section goes into the “effects” of the illness.)
    • Diagnosis
    • Expected Duration
    • Prevention
    • Treatment
    • When to Call a Professional
    • Prognosis

    For another example, see the “Use parallel structure for parallel sections” section below, which shows what a software troubleshooting article might look like.

    Order of importance

    The order of importance pattern organizes sections and subsections of content according to priority or significance. It is common in announcements, marketing brochures, release notes, advice articles, and FAQs.

    The order of importance pattern is perhaps the trickiest one to get right. As Carolyn Rude says, it’s not always clear what the most important information is. What should come in the beginning, middle, and end? Who decides? The answers will vary according to the author, audience, and purpose.

    When writing release notes, for example, my team often debates which software update should come first, because we know that the decision will underscore the significance of that update relative to the others. FAQs by definition are focused on which questions are most common and thus most important, but the exact order will depend on what you perceive as being the most frequent or the most important for readers to know. (If you are considering writing FAQs, I recommend this great advice from technical writer Lisa Wright.)

    Other common patterns

    Alphabetical order is a common pattern that Rude doesn’t mention in detail but that you may find helpful for your situation. To use this pattern, you would simply list sections or headings based on the first letter of the first word of the heading. For example, alphabetical order is used frequently to list API methods in API documentation sites such as those for Flickr, Twitter, and Java. It is also common in glossaries, indexes, and encyclopedic reference materials where each entry is more or less given equal footing. The downside of this pattern is that the most important information for your audience may not appear in a prominent, findable location. Still, it is useful if you have a large and diverse set of content that defies simple hierarchies and is referenced in a non-linear, piecemeal fashion.

    Group related material

    Take a look at the lists below. Which do you find easier to scan and digest?

    1. Settle on a version of D&D.
    2. Print a character sheet, if desired.
    3. Select a gender and race.
    4. Choose a class.
    5. Name your character.
    6. Identify the main attributes of your character.
    7. Roll for ability scores.
    8. Assign the six recorded numbers to the six main attributes.
    9. Use the “Point Buy” system, alternatively.
    10. Generate random ability scores online.
    11. Record the modifier for each ability.
    12. Select skills for your character.
    13. List your character’s feats.
    14. Roll for your starting gold.
    15. Equip your character with items.
    16. Fill in armor class and combat bonuses.
    17. Paint a picture of your character.
    18. Determine the alignment of your character.
    19. Play your character in a campaign.

    Part 1: Establishing the Basics

    1. Settle on a version of D&D.
    2. Print a character sheet, if desired.
    3. Select a gender and race.
    4. Choose a class.
    5. Name your character.

    Part 2: Calculating Ability Scores

    1. Identify the main attributes of your character.
    2. Roll for ability scores.
    3. Assign the six recorded numbers to the six main attributes.
    4. Use the “Point Buy” system, alternatively.
    5. Generate random ability scores online.
    6. Record the modifier for each ability.

    Part 3: Equipping Skills, Feats, Weapons, and Armor

    1. Select skills for your character.
    2. List your character’s feats.
    3. Roll for your starting gold.
    4. Equip your character with items.
    5. Fill in armor class and combat bonuses.

    Part 4: Finishing Your Character

    1. Paint a picture of your character.
    2. Determine the alignment of your character.
    3. Play your character in a campaign.

    (Source: wikiHow: How to Create a Dungeons and Dragons Character.)

    If you chose the second list, that is probably because the writers relied on a widely used organizational technique: grouping.

    Grouping is the process of identifying meaningful categories of information and putting information within those categories to aid reader comprehension. Grouping is especially helpful when you have a long, seemingly random list of information that could benefit from an extra layer of logical order. An added benefit of grouping is that it may reveal where you have gaps in your content or where you have mingled types of content that don’t really belong together.

    To group information effectively, first analyze your content and identify the discrete chunks of information you need to convey. Then tease out which chunks fall within similar conceptual buckets, and determine what intuitive headings or labels you can assign to those buckets. Writers do this when creating major and minor sections within a book or printed document. For online content, grouping is typically done at the level of articles or topics within a web-based system, such as a wiki or knowledge base. The Gmail Help Center, for example, groups topics within categories like “Popular articles,” “Read & organize emails,” and “Send emails.”

    It’s possible to go overboard here. Too many headings in a short document or too many topics in a small help system can add unnecessary complexity. I once faced the latter scenario when I reviewed a help system written by one of my colleagues. At least five of the topics were so short that it made more sense to merge them together on a single page rather than forcing the end user to click through to separate pages. I’ve also encountered plenty of documents that contain major section headings with only one or two sentences under them. Sometimes this is fine; you may need to keep those sections for the sake of consistency. But it’s worth assessing whether such sections can simply be merged together (or conversely, whether they should be expanded to include more details).

    Because of scenarios like these, Carolyn Rude recommends keeping the number of groupings to around seven, give or take a few—though, as always, striking the right balance ultimately depends on your audience and purpose, as well as the amount of information you have to manage.

    Use parallel structure for parallel sections

    One of the reasons Julius Caesar’s phrase “I came, I saw, I conquered” still sticks in our memory after thousands of years is the simple fact of parallelism. Each part of the saying follows a distinct, repetitive grammatical form that is easy to recall.

    Parallelism works in a similar manner with organization. By using a consistent and repetitive structure across types of information that fit in the same category, you make it easier for your readers to navigate and digest your content.

    Imagine you’re writing a troubleshooting guide in which all the topics follow the same basic breakdown: Problem Title, Problem, Cause, Solution, and See Also. In this case, you should make sure that each topic includes those same headings, in the exact same hierarchy and sequence, and using the exact same style and formatting. This kind of parallelism delivers a symmetry that reduces the reader’s cognitive load and clarifies the relationships of each part of your content. Deviations from the pattern not only cause confusion but can undermine the credibility of the content.

    Do This

    ABC Troubleshooting Guide

    • Introduction
    • Problem 1 Title
      • Problem
      • Cause
      • Solution
      • See Also
    • Problem 2 Title

      • Problem
      • Cause
      • Solution
      • See Also
    • Problem 3 Title

      • ...

    Don’t Do This

    ABC Troubleshooting Guide

    • Introduction
    • Problem 1 Title
      • Problem
      • Root causes
      • How to Fix it
      • Advanced Tips and tricks
      • Related
    • Problem 2 title

      • Issue
      • Steps to Fix
      • Why did this happen, and how can I avoid it next time?
      • See also
    • Problem 3 title

      • ...

    This last principle is probably the easiest to grasp but may be the most difficult to enforce, especially if you are managing contributions from multiple authors. Templates and style guides are useful here because they invite authors to provide standard inputs, but you will still need to watch the content like a hawk to squash the inconsistencies that inevitably emerge.

    Conclusion

    In one sense, my response to my former boss was accurate. Given the endless variety of writing situations, there is no such thing as a single organization solution. But saying that “advice varies widely depending on the situation” doesn’t tell the whole story. There are flexible patterns and principles that can guide you in finding, customizing, and creating structures for your goals.

    The key thing to remember is that structure affects meaning. The sequence of information, the categories you use, the emphasis you imply through your hierarchy—all of these decisions impact how well your audience understands what you write. Your ideal structure should therefore reinforce what you mean to say.

    Footnotes

    • 1. The principles in this article are based on the same ones that Carolyn Rude outlines in chapter 17, pp. 289–296, of the third edition of her book. I highly recommend it for anyone who’s interested in gaining an in-depth understanding of editing. The book is now in its fifth edition and includes an additional author, Angela Eaton. See Technical Editing (Fifth Edition) for details. The examples and illustrations used in this article are derived from a variety of other sources, including my own work.
Search Engine Watch
Keep updated with major stories about search engine marketing and search engines as published by Search Engine Watch.
Search Engine Watch
ClickZ News
Breaking news, information, and analysis.
PCWorld
  • This week in games: Battlefield V teases its battle royale mode, Deep Silver acquires TimeSplitters

    There are about a million games releasing, Gamescom is next week, PAX in two weeks—it’s starting to get pretty damn busy around here again. Both Brad Chacos and I will be in Germany for Gamescom next week, so keep an eye out for previews, announcements, and maybe even a video or two.

    But for now, a recap. It's mostly QuakeCon news this week, including 25 minutes of Doom talk, but you'll also find a smattering of early Gamescom trailers below, a tease for Vermintide II's first DLC, and a surprise TimeSplitters acquisition by Deep Silver. Remaster on the way? Let's hope.

    This is gaming news for August 13 to 17.

    Almost paradise

    As I said, Gamescom is still four or five days away—but not for everyone, evidently. Tropico 6 got out ahead of the competition and dropped this so-called “Gamescom Trailer” this week. Get ready to dance a bit in your seat while watching.

    To read this article in full, please click here

  • The best laptops: Premium laptops, cheap laptops, 2-in-1s, and more

    Today’s best laptops bask in the glow of Intel’s 8th-gen Core CPUs, which at last bring quad-core performance to mainstream machines. The only thing missing is Oprah shouting, “and you get an 8th-gen quad-core laptop!”

    There’s plenty of good news with this new generation. Our favorite convertible laptop, HP’s Spectre x360 13, sports a quad-core 8th-gen chip while maintaining its diminutive size. It’s really the total package. 

    But let’s be honest: You probably don’t need a quad-core powerhouse, especially if the hottest application you run is Microsoft Excel. Check out our budget favorites, like the Acer Aspire E 15 and Asus ZenBook Flip, whose dual-core CPUs do just fine with mainstream fare. Or read about the Asus Chromebook Flip, a well-priced and versatile laptop for living on the web—or delving into the wide, wide world of Android apps. 

    To read this article in full, please click here

  • The best CPUs for gaming

    Buying a processor for a gaming rig isn’t as hard as it used to be. Now that AMD’s Ryzen and Intel’s 8th-gen CPUs debuted with more performance and cores than ever before, it’s hard to buy a stinker these days—especially since most games favor graphics firepower over CPU oomph. But all that said, there are specific chips that stand out from the horde as the best gaming CPUs due to their price, performance, or nifty extras.

    Updated August 17, 2018 with confirmation of an Intel 9000-series by motherboard vendors.

    To read this article in full, please click here

  • How next-gen motion capture will supercharge VR arcades

    You might know motion capture as the tech that transformed Andy Serkis into Gollum, but now it can transform everyday people into animated avatars in virtual worlds, and all in real-time. Motion capture—which uses body sensors, ultra-precise cameras, and modeling software to create 3D animations from real-life human movement—is now taking on location-based virtual reality, or LBVR.

    PCWorld visited a leading motion capture company called Vicon in Oxford, England to learn how mocap has evolved to take on this new frontier in entertainment.

    If you’ve watched behind-the-scenes footage of how motion capture (or mocap) works, you’ve probably seen actors in skintight lycra suits covered with golf ball-sized sensors. Normally, dozens of infrared cameras track these sensors to model an actor’s movements. But now Vicon has a new system called Origin that requires only one sensor on each limb, plus one for a VR headset.    

    To read this article in full, please click here

  • Amazon slashes up to 20% off Fitbit Charge 2 as Charge 3 rumors heat up
CNN.com - RSS Channel - App Tech Section
CNN.com delivers up-to-the-minute news and information on the latest top stories, weather, entertainment, politics and more.
CNN.com - RSS Channel - App Tech Section
  • As competition for the world's first operational hyperloop heats up, CNN asks how the super-fast transport system could change lives and business in the UAE.
  • The next episode of "Declassified" explores the CIA's HEXAGON satellite, used to spy on the Soviet Union.
  • "Declassified" explains how the HEXAGON satellite program gave the U.S. an advantage over the Soviet Union.
  • Wonders of the universe
  • No Isolation founder Karen Dolva wants to use technology to help people stay connected.
 

Ако решите, че "как се прави сайт" ръководството може да бъде полезно и за други хора, моля гласувайте за сайта:

+добави в любими.ком Елате в .: BGtop.net :. Топ класацията на българските сайтове и гласувайте за този сайт!!!

Ако желаете да оставите коментар към статията, трябва да се регистрирате.