You’ve probably seen someone on the internet write funny-looking but runnable JavaScript code using only six different characters. But how does that actually work?
You can write basically any JavaScript program on the planet using just these characters:
This is a well-known trick, but not that many developers know how it actually works. Today, we’re gonna look at how it works under the hood. Let’s create the string "self" using only our funny little subset of characters.
Our target string will be "self", as an homage to the programming language Self for being one of the inspirations for JavaScript.
How It Works: The Basics
What allows us to make all other characters superfluous is the fact that we can abuse JavaScript’s type system and bizarre type conversion mechanisms.
We’ll be using our six superhero characters this way: with [] we can create arrays, with the negation and addition operators ! and we can do operations on them and finally use () to group operations.
Let’s start off with a simple array:
Negating an array with ! will coerce the array into a boolean. Arrays are considered to be truthy. Therefore, negating it will produce false:
Values of different types cannot be added together unless converted to similar types. JavaScript follows a pre-defined ruleset when doing conversions:
In the expression 2 true, JavaScript will convert true to a number, resulting in the expression 2 1.
In the expression 2 "2", JavaScript will convert the number of a string, resulting in 2 "2" === "22".
These conversion rules aren’t that bad, but it gets quite interesting quite quickly with other types.
JavaScript Array Coercions
Adding arrays together will convert them both to strings and concatenate them. Empty arrays turns into empty strings, so adding two arrays together yields the empty string.
[][]===""""===""
The same will happen when adding an array with something else, lets say, a boolean.
![][]==="false"""==="false"
Aha! Now we’re conjured a string containing the characters we need to produce our end goal, the string "self".
If we could produce some numbers, we could extract the characters we need in the right sequence:
"false"[3]==="s"(![][])[3]==="s"
Let’s go looking for numbers!
In the previous section, we coerced an array to a boolean.
What happens if we coerce it to a number using ?
JavaScript will attempt to call valueOf on the array, which will fail and fall back to calling toString() on the array.
Converting a string to a number will produce the following results:
"42"===42"esg"==NaN""===0
The empty string is a falsy value, like null, undefined and the number zero, so converting any of these to a number produces zero:
null===0undefined===0false===0NaN===0""===0
So converting an array to a number takes a detour converting to string first, finally producing zero:
Aha! We’ve managed to produce a number! Although, not a very useful one.
However, we can keep playing the coercion game:
!0===!false!false===true!0===true
Negating zero will make the falsy value of zero into a truthy boolean.
A truthy boolean as a number becomes… one!
Hooray! One one can become two ones… which is two. You get the point.
Using the substitutions we’ve learned to create numbers:
Arrays are truthful values, so negating them will produce false: ![] // false
JavaScript coercing rules state that adding arrays together will toString them: [] [] // ""
Converting an array to a number becomes zero, when negated becomes true, when coerced to number becomes 1: (!( [])) === 1
![][]==="false"![]===1(![][])[3](![][])[4](![][])[2](![][])[0]^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^"false""false""false""false"^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
s e l f
Recently I had been asked how I go about writing my articles each week because they are “really well structured and written”. As you could imagine I was massively flattered by this and as someone who struggles with reading and spelling, I felt proud of myself for not letting these struggles get the better of me. I instantly replied to this message with how I write my weekly posts as I had so much to say and share on how I do structure my writing.
My process for writing hasn’t always been successful and it’s something I’ve iterated and will continue to do so but I feel that my formula so far has worked out quite well. The more time I’ve spent thinking about my writing process it has led me to realise that it feels incredibly similar to my design process. Perhaps because I’m a stickler for systems and methods is why I’ve mimicked my design process when it comes to writing.
Ideas are at the core of what we do as designers, without a solid idea it’s really difficult to know what direction to take but also it means a lot of work can be based on style rather than substance. Just like writing, you may have an essay worth 1,000 words, but without a solid idea, you’ll end up writing nothing.
I try to write once a week, specifically focusing on reflecting upon that week and what I’ve learnt. This process has turned into a key way of generating writing prompts and inspiration for me. Sometimes I will have two ideas in a week, other times I will have a spark of inspiration on a Monday which I have to just type out, then there are times when I have to sit down and reflect on the week to see if there was anything learnt even in the most subtle moments.
Just like in design, any idea can be built upon through talking with clients, friends, by doing research and so on. As long as you have an idea to start with that you are interested in or passionate about design or in this case writing about, then this is the most important part.
The audience. Whether we’re talking about the design process or the writing process there will always be someone this piece of writing is for. With that in mind, everyone can’t be your audience. In user experience design we focus a lot on this principle that you can’t design for everyone and if you try to, ultimately please no one. If you try to write for the world and have no focus on who you’re writing for, it will become incredibly difficult to write. By giving yourself someone to write for you’ll make your life easier but also it means your writing will be more interesting and coherent.
When I write, I write intending to teach someone something. This is where my comparison to the design process differs slightly. I leant into writing to inform as I’m trying to write for myself — but I don’t mean literally. I use myself almost like a persona. I love learning so I write my articles from a place of teaching. I’m also interested in self-help, career progression and design, and it’s these interests and topics all feed into the kind of person I’m writing for.
Once the idea you want to solve is set, in the design process, particularly digital product design you would then come up with a user flow. When working on a design project I like to go through this stage multiple times adding layers of detail as I go. For example, I will always start with a very high-level overview of the process that a user will take; There is always a start, middle and end in this users journey. Next, I will look into each of those three sections and add rough ideas such as the user may sign up to the website, they will have to add card details, they will get an email and so on. This process happens before fully fleshing out the details screen by screen.
When it comes to writing I apply this same method. All of my articles have an introduction, the main content, then a conclusion. Within each section, I would add bullet points or subheadings of the main points I want to get across and from there add more detail as to what I want to get across in those subheadings. For example, in the introduction, I will make a note to make sure I tell the readers how I was inspired to write the article, as well what the main idea or theme is that I will be writing about.
Once I am confident in the structure of my article, set out by creating a user flow I will then use this to help me create the wireframe. In design, the wireframe is the first time you start planning out screens, looking at where content will sit to each other and looking at what the content is and how it will best serve the users.
Interms of writing the wireframe is the first draft of the article. This writing wireframe doesn’t have to be neat or perfect it just needs to get the hierarchy of content there as well as the main themes and ideas that were set out in the user flow. The first draft is some times the hardest so it’s best to get this initial writing wireframe out on paper — or on-screen! With as little judgement as possible, if you’re fussing over every word used or sentence you’ll never finish.
As every good designer does in their process they iterate. The iteration phase when looking at writing would be going through the content that you’ve created and looking back and checking whether the points set out in the user flow have been met. Just like our design projects, sometimes we miss things the first time around and we iterate on wireframes. Sometimes our first layout isn’t now working for us or there might be a better solution. Keep going over your content until you are sure you’ve got all the key points and in the right order that will get your idea across.
Finally, the home stretch, add the interface. In digital product design, the interface is incredibly important. If we have an awful looking colour palette, pixelated images and a font so small people can’t read it then it doesn’t matter how good the content is, no user will stay to find out.
The interface of writing is just as important. When talking about writing in this way, I’m talking about the details of how the words are being presented. This means making sure that the writing looks nice too as well as being interesting and useful. That means having the title of the article in sentence casing, ensuring the proper use of quotes or paragraphs, adding images to your article to help illustrate your points. There are a lot of written articles on the web that have brilliant content but formatted badly and if a user can’t navigate through your writing due to the lack of paragraphs or subheadings then that would be an incredible shame.
When sharing your design work with the world, we test them with our existing or potential audience. We do this so that we can make sure we great the best product for our audience, and testing allows to check for things that we have missed or might not though we’re needed in the beginning. When we are testing our products we don’t do this to see whether the product is worth creating, unless of course we’re researching the product-market fit, but we share so we can get feedback on how to improve.
In the writing process, I follow the same tactics and you could too. There are varying levels of feedback you can get, some may give you feedback on the topic or idea, others may point out missing words and this feedback is very useful. But we don’t want to use this feedback to determine if we should or shouldn’t share our writing at all. If we believe that the topic is interesting and that it has an audience out there then it will always be worth sharing.
I tend to focus on the feedback part of the writing process a lot, and it’s the same with my design process. I don’t claim to know everything and I love to hear the ideas and perspectives of others and how I can improve what I’ve created.
Also as someone who struggles with grammar and spelling, I must have someone to sense check what I’ve written. Not that I’m embarrassed about making mistakes like this, but I’d rather ask for help and have my writing published first time round on Medium, compared to if I skipped feedback entirely and then had readers leaving comments about weird spelling errors or silly mistakes I’d made.
The similarities between writing and the design process are apparent when you start to look at them in parallel. Naturally, I’ve spoken about my design and writing process and I’m not saying it’s best but it works well for me at the moment. You may have your processes which work, and that’s great as long as your method gets you writing and sharing your great thoughts and opinions then that’s all that matters.
I’ve found that a lot of people, especially designers struggle with writing — whether it’s a Medium article or an email to their client explaining what they’ve done and why. My opinion is that especially blog posts people fear that it’s going out into a public space. People worry about sharing their thoughts and opinions and they worry about not having anything interesting enough to say or the writing quality not being good enough.
I always say that everyone can design (which some designers hate me for saying) but I also believe everyone can write. With the right structure and processes in place, anyone can do it with practice.
Remember: The first sentence is the hardest to write. And that’s because people put too much pressure on themselves to write a brilliantly engaging group of words from the get-go. But like any successful design project by having a plan, structure, multiple interactions means that you can get your writing into a state that you’re proud of and something you’ll no longer fear!
Do you think the design process is the same as writing? Do you enjoy writing or do you get the fear of a blank page? Get in touch and let me know in the comments! Or you can find me on Twitter as @lizhamburger
You might be surprised to find out that writing and designing have their fair share of similarities. In this post, Eugen Eşanu explains how the act of writing is extremely beneficial to designers and shares some tips for exercising your writing skills.
Recently, I wrote a story about how important it is to develop good communication skills—whether you are a designer, manager, or a CEO. But I didn’t explain what actually led me to become a better communicator myself and that is — writing.
“Writing helps you think and learn, enhances your chances of success, contributes to your personal development, and strengthens your relationships with other people” — Axelrod&Cooper
Writing helped me to become a better designer, leader, and thinker. As a designer, my job is to take a mess of ideas and issues and transform them into a product or solution. Writing helped me learn how to clean the clutter and make products that delight people.
Believe it or not, there are many similarities between writing and design. For example, when you write an article, you have to choose what ideas to leave or remove. In design, you have to choose what features to keep, add, remove, or redesign. In writing, you have to make your ideas clear so that anyone can understand them. In design, your UI has to be self-explanatory.
So, here is how consistent writing can make you a better designer.
1. Writing will influence the way you think
Writing is like going to the gym for your brain. The act of writing encourages you to be organized and logical in your thinking. When you write a sentence, paragraph, story, or even an essay, you train your brain to think concisely and consistently.
For example, once you notice that you repeated your thoughts in a paragraph, you change it and remove it. This exercise helps you think in different ways and also notice redundancies.
Your writing doesn’t have to be about design. Writing about any topic will enable you to reflect on those actions and/or experiences. Writing about an event that happened will inspire you to think about what happened and why it was memorable. This way, you are more in touch with yourself.
2. Writing will help you grow
Writing is a way of tracking our own progress. Teresa Amabile, a Harvard Business School research director, discovered that people feel more engaged and productive when they record in writing even the smallest of accomplishments. The more you are aware of your progress, the more involved you are.
“Writing helps you remember what you are studying or doing, by leading you to analyze and connect information and ideas from different sources” — Axelrod&Cooper
Writing or taking notes as you read or listen makes you a better listener — another crucial skill for designers. Writing down reflections about what you are learning from your users, team, books, or life, consolidates your thoughts and improves your intuition.
3. Writing will clear the clutter
Writing helped me communicate much better with developers. It made me think more logically and less abstract, so others could understand my needs.
Whenever I have to hand over a product design to developers, I write about two-pages worth of steps to be taken. Then, I reread it to see if it makes sense. After that, I ask a non-designer friend to give it a read and tell me whether they understand it. The goal is to write everything so clearly that even a stranger who has no context about the job can understand it. If they aren’t able to understand it, I go back and make changes.
“The mere process of writing is one of the most powerful tools we have for clarifying our own thinking. I am never as clear about any matter as when I have just finished writing about it” — James Van Allen
4. Writing will help you become even more creative
Writing keeps your creativity goings strong. I always have a small notebook with me (or the notes app on my phone) so every time I walk, read, or talk to someone, I can take quick notes on random ideas that pop into my head. Later on, I connect my ideas and create product features or find solutions for current issues. Or even article ideas like this one 😉
5. Writing will help you become a better leader
Besides helping you to argue and explain your decisions, writing will make you a better leader. Arguing a position in writing teaches you not only to support your reasoning, but also to answer objections to your argument. You will be able to explain why it is necessary to do this or that, and communicate a clear vision and guidance for your team.
There’s nothing worse than a leader who desmands something that is unclear.
Let’s say you are about to introduce a new working process for your company — design sprints. Explaining the concept requires you to inform yourself about your subject and organize the information in a way that makes it clear to readers and listeners. That’s why writing before presenting or speaking is the best way to clean your thoughts and get them across effectively.
A few side-notes…
Write with pen & paper
If you can, try to write and take notes with pen and paper because it benefits your brain. Every time you do a user interview or testing, conduct research, or have a call with a client, write everything down on a piece of paper so you can remember and understand it better.
In a study , two groups of students were asked to take notes during a lecture. One group wrote their notes on paper, the other on their laptops. They found that the students who took notes by hand performed significantly better than those who typed them out. Taking notes by hand helped these students remember and recall what they wrote down, and also improved their long-term memory.
“…there is something about typing that leads to mindless processing. And there is something about ink and paper that prompts students to go beyond merely hearing and recording new information…”
Taking notes by hand leads to quality learning, as writing is a better way to store and understand ideas over time. Writing by hand strengthens the learning process, while typing can weaken it. A similar study published in Intech found that writing by hand allows the brain to receive feedback from your motor actions, and this feedback is different than those obtained when typing on a keyboard. You’ll improve how your brain develops, benefiting your thinking and creativity.
Writing doesn’t have to be a pain
For some, writing can be a pain. The act of getting your ideas across clearly on paper is hard work. Not to mention, from an early age we were forced to write essays in school, meeting a minimum word count — it’s as if it was ingrained in us that writing is an unpleasant experience. But, if you understand that you can write about anything you want, writing becomes easier to approach.
I began writing two years ago. My first articles were about games because that’s what I enjoyed at the time, and it motivated me to keep writing. Then, I couldn’t stop. I was motivated to write much more, even if some of my articles didn’t get as much recognition as others. Every time I hit the publish button, I felt a sense of relief. It was a pleasure to get all of my ideas out and share them with others.
How can you begin writing?
To write about something, you have be inspired. To be inspired you have to read, listen, talk to others, or think first. Many creators and inventors consume inspiration from all sources before they create or write something. Whether it’s going to a museum, visiting a new city, meeting people, listening to a podcast or presentation, you have to consume first and then create.
You can’t be inspired if you don’t consume inspiration.
There is no magic moment
Writing is hard. The only way to get better at it is — to simply start writing. Open up that blank page and write words on it. About what? Anything. What you learned today at work or an experience with a client. Write about an occasion when writing helped you better understand a difficult subject. Or an occasion when your writing made others take notice. Write about your design process, challenges, mistakes, dogs, weird hobbies — write about anything. Write every day. Let it out and let others read it.
Also, there is no such thing as writer’s block. It’s a myth. It means that you are a perfectionist and can’t stand bad writing. When you say I can’t write, you actually mean “I can’t write something that is perfect”. If you write poorly enough a lot, sooner or later, your brain will give up and you will start writing great. Write 50,000 words of bad writing and then let everyone around you decide if you can write or not.
Oh, email. Love it or hate it, email remains “the backbone of what we do, especially when you get into a managerial position,” for most professionals, says Victor Pineiro, the creative director of Big Spaceship, a marketing agency in Brooklyn.
This extends to connecting two people who have never met IRL, which is often the only realistic way to introduce two busy people. While a good email intro “makes you feel seen,” says Erin McKean, the founder of the online dictionary Wordnik.com, “a bad introduction makes you feel like a subcontractor in a business you don’t run. I’ve gotten some intros in the past that were essentially ‘Please do some tedious and unrewarding work for this person so I don’t have to.’”
Luckily, how to write and respond to introductions over email is a skill that can be learned. Below, professionals who have sent (and received) their fair share of introductory emails share tips for mastering the craft.
But first, a note: When receiving an introductory email, it’s important to remember the stakes, which are usually, in the grand scheme of things, quite low. Yes, receiving a poorly constructed introduction is annoying and potentially time-consuming. “But we need to be much more vigilant about our own behavior and much more forgiving of others’ behavior,” says William Schwalbe, who co-wrote Send: Why People Email So Badly and How to Do It with David Shipley. “As a fundamental rule, there are worse problems in the world than people we know trying to introduce us to someone.”
On to strategies for how to do email introductions right.
***
Ask for opt-ins.
As a general rule, check that both parties are receptive to the introduction before facilitating the connection. “Make sure the people being intro-ed know this email is coming,” says Polina Marinova, an editor at Fortune Magazine and the creator of The Profile, a newsletter that rounds up the best profiles on the Internet each week. “Do not surprise.”
In other words, the first step in a successful email introduction is rarely the introductory email itself. Instead, start by messaging the sought-after party and asking “‘Hey, I’d love to introduce Jane to you; she’s working on a new project that I thought you’d love to hear about, and she has questions about X, Y, and Z that you could be really helpful in answering for her,’” McKean says. “And then you wait.” You can follow-up once or twice, “but if you don’t hear back, you drop it.”
Pre-intro checks don’t always have to be formal. If you know one of the parties well, it can be as simple as sending a text or a message on Slack. No matter the method, “it’s great to get a heads up, especially if someone is very busy or super senior to make it easier on everybody,” Pineiro says.
As the connector, it’s also good protocol to make the mechanisms of the introduction clear to both parties: “I don’t mind if someone asks for a favor, but don’t pretend you are doing me a favor if I am doing you a favor,” Schwalbe says. And if you are asking for a favor, make sure it’s a request worth making. “Most bad intros are bad because either the person making the intro or the person being introduced conveys a sense of unwarranted entitlement to your time and energy,” McKean says.
Should you receive an intro request you’d like to decline, go ahead and say no. “‘Gosh, I wish I could,’ is a great universal response,” Schwalbe says. You can explain yourself if you’d like, “but you don’t have to give a reason.”
Evaluate the power dynamics.
Like snowflakes, no two introductory emails are exactly the same. One of the most important variables is the power dynamics between the two people being introduced. Oftentimes, there is a clear imbalance, such as when you are connecting a job seeker with a potential job giver, Schwalbe says. In cases like this, it’s crucial to privately check in with both parties beforehand, especially the person with more power to ensure they are up for the introduction.
In instances where the power dynamic is equal, Schwalbe says he doesn’t always pre-clear an introduction because it’s less transactional in nature. Just make sure the power dynamics are truly level. “If one person is immediately going to want something from the other person, even if they are of equal standing, then it reverts to case one,” Schwalbe says.
State the reason for the introduction.
A good introductory email makes its purpose clear. “The hardest thing is when you don’t know why someone is introducing you,” Schwalbe says, a situation in which it’s easy “to disappoint just because you didn’t know what was expected of you. It’s awkward.”
After explaining why he is making the introduction, Pineiro sometimes likes to nudge one person to take the next step. Often, this is the person who has more to gain from the exchange: If, for example, Pineiro was to introduce his nephew to a CEO of a company, he’d make it clear that his nephew should reply first.
Either way, after making the initial intro, make it clear that your job is done. “End it with ‘I’ll let you guys take it from here’ and don’t involve yourself more,” Marinova says.
Schwalbe’s go-to sign-off is a firm but polite: “I’ll leave it to the two of you to be in touch with one another. Please feel free to leave me off the thread going forward.”
Provide context.
This ties directly back to the previous strategy: Not only should your introductory email’s purpose be clear, but you should explain who each person is and, when necessary, what they do. “‘This person is really cool!’ is not context,” McKean says “Don’t make me try to glean from LinkedIn or Twitter what kind of questions might be asked of me.”
Often, this means including a brief professional bio. Hyperlinks, to websites or bodies of work, are your friend here. “If I say someone is an amazing writer, I’d link to one great story she did,” Marinova says.
Under the right circumstances, this is also the place to include personal details. When making an email introduction, Pineiro tries to include one fact about each person that is not work-related. It could be a shared interest, or something out of left field, like “John knows Mick Jagger.” In Pineiro’s experience, such details, no matter how random, make it easier for people to kickstart a conversation that sounds human rather than robotic.
Keep it short.
“Always ask yourself: What’s the point of this email? Cut out the small talk that normally clutters the beginning of emails,” Marinova says. “No one wants to read big blocks of text…especially for a first email.”
In addition to being time-consuming, a wall of words can be intimidating. “The longer you make your email, the more pressure it creates,” Pineiro says. As he’s gotten older and climbed the corporate ladder, he’s learned to pare down his email style. “When I was younger, the impetus was ‘let me write out my biography and send it to this person,’” he says. He now recognizes the value of keeping it friendly, but concise.
Avoid hyperbole.
Connecting two people can come with the well-intentioned impulse to talk up both parties, which explains why so many introductory emails are riddled with superlatives.
This is often unnecessary. “I don’t need to hear too much praise in your intro, especially not of myself,” McKean says. “If I trust you enough to be interested in your introduction, I don’t need to be flattered to take it.”
Taken too far, hyperbole can be counterproductive. Overselling, particularly when it comes to someone’s job title, is a recipe for awkward moments. (Erroneously promoting someone from an associate at a law firm to a partner, for example, creates a situation in which they are forced to clarify.)
“Everyone doesn’t have to be amazing. It’s a sweet impulse, but it can actually makes people feel badly,” Schwalbe says. If you must embellish, “you can exaggerate someone’s personal qualities without exaggerating their professional qualifications.”
An understanding of CSS Writing Modes is useful if you want to work with vertical scripts, or change writing mode for creative reasons. However, they also underpin our new layout methods, and those ideas are increasingly being applied across all of CSS. In this article, find out why Rachel Andrew believes understanding writing modes is so important.
This is not an article about the practical or creative application of this property. Instead, I want to demonstrate why understanding writing modes is so important — even to those of us who rarely need to change the writing mode of a page or component. The support of multiple writing modes is key to the way that our new layout methods of Flexbox and Grid Layout have been designed. Understanding this can unlock a better understanding of how these layout methods work.
What Are Writing Modes?
The writing mode of a document or a component refers to the direction that text flows. In CSS, to work with writing modes we use the writing-mode property. This property can take the following values:
horizontal-tb
vertical-rl
vertical-lr
sideways-rl
sideways-lr
If you are reading this article on Smashing Magazine in English, then the writing mode of this document is horizontal-tb, or Horizontal Top To Bottom. In English, sentences are written horizontally — the first letter of each line starting on the left.
A language such as Arabic also has a horizontal-tb writing mode. It is written horizontally, top to bottom, however Arabic script is written right to left, and so sentences in Arabic start on the right.
Chinese, Japanese and Korean are written vertically, with the first character of the first sentence being top right. Following sentences being added to the left. Therefore, the writing mode used is vertical-rl. A vertical writing mode running from right to left.
Mongolian is also written vertically, but from left to right. Therefore, should you want to typeset Mongolian script you would use the writing mode vertical-lr.
The other two values of writing-mode are designed more for creative purposes than for typesetting vertical scripts. Using sideways-lr and sideways-rl turns text sideways — even characters normally written vertically and upright. The values, unfortunately, are only supported in Firefox at the moment. The following CodePen shows all of the different values of writing-mode, you will need to use Firefox if you want to see the sideways-* ones in action.
See the Pen [Writing Mode demo](https://codepen.io/rachelandrew/pen/dxVVRj) by Rachel Andrew.
Writing Modes can be used when creating a document that uses a language written using that writing mode. They can also be used creatively, for example, to set a heading vertically down the side of some content. In this article, however, I want to take a look at the impact that supporting vertical languages, and the possibility of vertical text, has on CSS layout, and across CSS in general.
Before I do so — if you are interested in the use of writing modes for vertical text — here are some useful resources:
The W3C Internationalization site has a wealth of useful information. Read about RTL scripts and vertical text.
Jen Simmons wrote an excellent article about CSS Writing Modes which also includes several examples from print of these modes in use.
When we change the writing mode of a document, what we are doing is switching the direction of the block flow. Therefore, it quickly becomes very useful for us to understand what is meant by block and inline.
One of the first things we learn about CSS is that some elements are block elements, for example, a paragraph. These elements display one after the other in the block direction. Inline elements, such as a word in a sentence display one after the other in the inline direction. Working in a horizontal writing mode, we become used to the fact that the block dimension runs top to bottom vertically, and the inline dimension left to right horizontally.
As block and inline elements relate to the writing mode of our document, however, the inline dimension is horizontal only if we are in a horizontal writing mode. It doesn’t relate to width, but instead to inline size. The block dimension is only vertical when in a horizontal writing mode. Therefore it doesn’t relate to height, but to block size.
Logical, Flow-Relative Properties
These terms, inline size and block size are also used as the names of new CSS properties designed to reflect our new writing mode aware world. If, in a horizontal writing mode you use the property inline-size instead of width, it will act in exactly the same way as width – until you switch the writing mode of your component. If you use width that will always be a physical dimension, it will always be the size of the component horizontally. If you use inline-size, that will be the size in the inline dimension, as the below example shows.
See the Pen [width vs. inline-size](https://codepen.io/rachelandrew/pen/RXLLyd) by Rachel Andrew.
The same is true for height. The height property will always be the size vertically. It relates to how tall the item is. The block-size property, however, gives the size in the block dimension, vertically if we are in a horizontal writing mode and horizontal in a vertical one.
As I described in my article “Understanding Logical Properties And Values”, there are mappings for all of the physical properties, those which are tied to the dimensions of the screen. Once you start to think about it, so much of CSS is specified in relation to the physical layout of a screen. We set positioning, margins, padding and borders using top, right, bottom, and left. We float things left and right. Sometimes tying things to the physical dimension will be what we want, however increasingly we are thinking about our layouts without reference to physical location. The Logical Properties and Values specification rolls out this writing mode agnostic way of working right across CSS.
Writing Modes, Grid And Flexbox
When our new layout methods landed on the scene, they brought with them an agnostic way of looking at the writing mode of the component being laid out as a flex or grid layout. For the first time people were being asked to think about start and end, rather than left and right, top and bottom.
When I first started to present on the subject of CSS Grid, my early presentations were a rundown of all of the properties in the specification. I mentioned that the grid-area property could be used to set all four lines to place a grid item. The order of those lines was not, however, the familiar top, right, bottom and left we use to set all four margins. Instead, we need to use top, left, bottom, right – the reverse of that order! Until I understood the connection between grid and writing modes, this seemed a very odd decision. I came to realize that what we are doing is setting both start lines, then both end lines. Using top, right, bottom and left would work fine if we were in a horizontal writing mode, turn the grid on its side however and that makes no sense. If we use grid-area: 1 / 2 / 3 / 5; as in the pen below the lines are set as follows:
grid-row-start: 1; – block start
grid-column-start: 2 – inline start
grid-row-end: 3 – block end
grid-column-end: 5 – inline end
See the Pen [grid-area](https://codepen.io/rachelandrew/pen/zgEEQW) by Rachel Andrew.
If you use Flexbox and add display: flex to a container, your items will display as a row as the initial value of the flex-direction property is row. A row will follow the inline dimension of the writing mode in use. Therefore if your writing mode is horizontal-tb a row runs horizontally. If the text direction of the current script is left to right then items will line up starting from the left, if it is right to left they will line up starting on the right.
Use a vertical writing mode however, such as vertical-rl and flex-direction: row will cause the items to lay out vertically, as the inline direction is vertical. In this next CodePen all of the examples have flex-direction: row, only the writing mode or direction has changed.
See the Pen [flex-direction: row](https://codepen.io/rachelandrew/pen/XvezrE) by Rachel Andrew.
Add flex-direction: column, and the items layout in the block dimension of your writing mode. In a horizontal writing mode the block dimension is top to bottom, so a column is vertical. With a writing mode of vertical-rl a column is horizontal. As with the previous example, the only difference between the below flex layouts is the writing mode being used.
See the Pen [flex-direction: column](https://codepen.io/rachelandrew/pen/RXLjbX) by Rachel Andrew.
When using auto-placement in grid, you will see similar behavior to that in flex layout. Grid items auto-place according to the writing mode of the document. The default is to place items in rows, which will be the inline direction – horizontally in a horizontal writing mode and vertically in a vertical one.
See the Pen [Grid auto-placement row](https://codepen.io/rachelandrew/pen/eqGeYV) by Rachel Andrew.
Try changing the flow of items to column as in the example below. The items will now flow in the block dimension – vertically in a horizontal writing mode and horizontally in a vertical one.
See the Pen [Grid auto-placement column](https://codepen.io/rachelandrew/pen/xvXPby) by Rachel Andrew.
Line-based placement also respects writing mode. The lines of our grid start at 1, both for rows and columns. If we position an item from column line 1 to column line 3, and are in a horizontal writing mode with a left to right direction, that item will stretch from the left-most column line across two grid tracks horizontally. Thus spanning two columns.
Change the writing mode to vertical-rl and column line 1 will be at the top of the grid, the item spanning two tracks vertically. Still spanning two columns, but the columns are now running horizontally.
See the Pen [Margins: adjacent siblings](https://codepen.io/rachelandrew/pen/mNBqEy) by Rachel Andrew.
One of the first places many people will have come into contact with the way Flexbox dealt with writing modes, would be when aligning items in a flex layout. If we take the flex-direction: row example above, and use the justify-content property to align all of the items to flex-end the items move to the end of their row. This means that in a horizontal writing mode with left to right direct the items all move to the right, as the end of that row is on the right. If the direction is right to left, then they all move to the left.
In the vertical writing mode, they move to the bottom, assuming there is space for them to do so. I have set an inline-size on the components in this example to ensure that we have spare space in our flex containers to see the alignment in action.
Alignment is a little easier to understand in grid layout, as we always have the two axes to play with. Grid is two-dimensional, those two dimensions are block and inline. Therefore, you can remember one rule if you want to know whether to use the properties that begin with align- or those which begin with justify-. In grid layout the align- properties:- align-content, align-items, align-self are used to do block axis alignment. In a horizontal writing mode that means vertically, and in a vertical writing mode horizontally.
Once again, we don’t use left and right or top and bottom, as we want our grid layout to work in exactly the same way no matter what the writing mode. So we align using start and end. If we align to start on the block dimension, that will be top when in horizontal-tb, but will be right when in vertical-rl. Take a look in the example below, the alignment values are identical in both grids, the only difference is the writing mode used.
See the Pen [Margins: adjacent siblings](https://codepen.io/rachelandrew/pen/jgGaML) by Rachel Andrew.
The properties justify-content, justify-items, justify-self are always used for inline alignment in grid layout. That will be horizontal in a horizontal writing mode and vertical in a vertical writing mode.
See the Pen [Margins: adjacent siblings](https://codepen.io/rachelandrew/pen/RXLjpP) by Rachel Andrew.
Flexbox alignment is complicated somewhat by the fact that the main axis can be switched from row to column. Therefore, in Flexbox, we need to think about the alignment method as the main axis versus cross axis. The align- properties are used on the cross axis. On the main axis, all you have is justify-content because we deal with items as a group in Flexbox. On the cross axis, you can use align-content in cases where you have multiple flex lines and space in the flex container to space them out. You can also use align-items and align-self to move the flex items on the cross axis in relationship to each other and their flex line.
See the Pen [Flexbox alignment](https://codepen.io/rachelandrew/pen/YmrExP) by Rachel Andrew.
Not all of CSS has fully caught up with this flow-relative, writing mode agnostic way of working. The places where it has not start to stand out as unusual the more you think of things in terms of block and inline, start and end. For example, in a multi-column layout, we specify column-width, which really means column inline-size, as it isn’t mapped to the physical width when working in a vertical writing mode.
See the Pen [Multicol and writing-mode](https://codepen.io/rachelandrew/pen/pMWdLL) by Rachel Andrew.
As you can see, writing modes underpin much of what we do in CSS, even if we never use a writing mode other than horizontal-tb.
I find it incredibly helpful to think about CSS layout in this writing mode agnostic way. While it is perhaps a little early to be switching all of our properties and values to logical ones, we are already in a flow-relative world when dealing with new layout methods. Having your mental model be one of block and inline, start and end, rather than tied to the four corners of your screen, clarifies many of the things we come across when using flexbox and grid.
Writers are motivated by the endless possibilities the blank page can afford. Writing without rules, your imagination can run riot. The image you create can be as abstract as you want. The canvas as big as you want.
So what happens when you add restrictions? Take space, for example. Now, your words need to fit inside a width of 70 pixels. Or take lexicon. No longer can you adorn your phrases with words like lexicon and adorn. And don’t forget syntax — make sure you use active voice, not passive voice.
Welcome to UX writing. It’s less like tackling a blank canvas, more like putting puzzle pieces together. Which can be immensely satisfying. But does it curtail a writer’s creativity? Does it reduce writing to what is, essentially, a paint-by-numbers exercise?
In other words, is UX writing ****ing boring?
Yesterday I was working on some ‘nudges’ in our app. Once someone creates their first typeform, we show them this message to inspire new ways to use the product.
One of our product managers suggested this instead:
How Barcelona’s best burger joint keeps sizzling with feedback
With my writer’s hat on, the suggested title is nicer. I like the word sizzle. I imagine a grill.
With my UX writer’s hat on, I think:
Is it clear what ‘keeps sizzling’ represents? If feedback is the activity, what’s the end result? There are a range of readings here.
We have users whose first language is not English. Would they all understand ‘joint’ and ‘sizzle’?
We’re asking someone to stop what they’re doing, jump out of the product, and read an article. Is it perfectly clear what they’re going to learn from reading the article?
My response was to leave the sizzle to one side and stick with the original title (or improve it) in the product. We can use the more eye-catching title for the blog article.
Evocative loses out to straightforward.
When it comes to UX writing, this ‘boring’ hangup we have is a personal insecurity. Our users aren’t scanning to be entertained (okay, some might. But they’re the exception). They’re scanning to quickly understand and take action. They’ve got something else in mind — something much more important than chuckling at our self-indulgent jokes.
It’s the difference between tourists and commuters. On the metro, tourists (to the frustration of regular commuters) value the experience in and of itself. They soak it up. Wallow in it. Wow, these trains are so much smaller! Look at all those lines! Ha, she said it — mind the gap! Commuters, on the other hand, just want to get to their destination as fast as possible. Simple communication like exit, step-free access, and doors open on the right-hand side provides just the essentials for doing so.
When I first started working on Typeform’s product, I thought I’d add my so-called personality to it. This is my time, I thought. Finally, I can show the world how creative I am.
An opportunity came up. We added a message to warn users that deleting a question from their typeform would also delete the logic they’d applied to that question.
Ha! I proclaimed, triumphant. A romantic relationship. I’m the king of metaphors.
Problem is, it’s the David Brent of system messages — desperate to get the joke in before you even know what’s going on.
A more effective message immediately tells you what’s going on, even if that means canning the comedy act.
Here’s another example from our old signup page:
And here’s what people thought about it:
Believe it or not, creepy and pervy, aren’t in our voice and tone guidelines. Point taken, copy changed:
Not only is the new copy not creepy, it actually gives you some useful information. Big thanks to Yuval Keshtcher and his UX Writing Hub community for the feedback.
In these cases, boring is beside the point. If things aren’t clear, you might as well be telling a joke to a cupboard door.
There seems to be a ‘voice and tone curve’ that companies follow as they grow. Back in 2015, Mailchimp used to explicitly state that its voice was fun and weird.
Mailchimp’s Content Style Guide in 2015
Fast-forward to 2019. They still say they’re weird, but the emphasis is very much on plainspoken, and their humour is dry. We recently interviewed Erin Crews, Senior Content Strategy Manager at Mailchimp. Here’s what she said:
“We’ve spent a lot of time defining a more dry, deadpan style of humor as we grow up and move into more complex product spaces.”
Mailchimp’s Content Style Guide in 2019
At Typeform, as we’ve grown up, we’ve wrestled with this swing from merry to meh.
Take a look at our question tooltips from a year ago:
We had a grand old time thinking up a funny example for each question type. Then we realised they weren’t really the clearest way to show what each question was for.
Compare it to the copy we have now:
It’s only natural that the emphasis on clarity increases as you grow. With a small audience, you can afford to be a bit more niche. In fact, it might even be one of the reasons your early adopters are attracted to you. You’re refreshing. You offer something different.
As you expand, you start to reach people in other countries. Unless you truly localise your product, the jokes your early tribe find hilarious might leave your international audience clueless.
So you revise all your copy for distracting messages. You shed your identity as class clown. What’s left? Who are you?
Of course, you can be both helpful and interesting. There are tons of examples of companies who have done it effectively. The trick is knowing when to sprinkle on the fun flakes.
Clearing all those unread messages is a good feeling. The Slack team know it’s the right time to celebrate:
Now imagine you arrive at the airport. You left your house in a hurry, and you’re panicking about what time your flight leaves. You glance at the departures board.
At Stansted airport, they let you know you have time to relax:
And at the Typeform office, once you know the water’s not drinkable, we figured it’s fine to throw in a cheeky aside.
If you’re someone who needs constant stimulation, perhaps. If you need everything to be on, all the time, like a method actor who never drops his character — then yes. The world might be a boring place for you.
Because good UX helps us navigate the world smoothly. If those same things were to distract us in the process it would defeat the purpose. A metal plate on a door tells us to push. A handle tells us to pull. We don’t think about it, we just act.
Push or pull? Most people wouldn’t even think about it.
But for brands to connect with people, they need to be different. This is the enticing paradox of good UX: stand out, fade away. It means raising a smile while keeping someone on track. And that means finding a spark of creativity within a set of restrictions.
“We’re willing to be weirder than anyone else. That’s still something that sets us apart that we really embrace. And we’re not terribly worried about other companies adopting that.”
So no, UX writing isn’t boring. You just need to find a way to make your desk a door.
Nowadays, as a webdeveloper, you rarely build anything from scratch: your daily job mostly consists of integrating various Javascript libraries together. If you are building a web app you are most likely going to use some framework like React, Vue or Angular for your front-end. To transmit and manage the data you will be using Redux or GraphQL. For the backend, there will be Express and probably Loopback. Then you need to cover everything with tests, so Jest, Mocha or Jasmine must be present too. Finally, there will be UI frameworks like Bootstrap and maybe some charting tools. I have already counted at least 7 core libraries and all of these are in a single project! And what about underlying technologies like Javascript itself, Node.js and, probably, Typescript? Well, that’s a lot!
So how do you learn all of these tools? Of course there is a such thing as a documentation.
Why documentation is important?
There are two ways you can relate to documentation: you can either write or read one. Sometimes you are on both sides, but in most cases you are consuming a creation of other developers. You would not use any of the mentioned libraries, unless they were well documented, would you? Which brings us to the first point:
People will not even consider your project unless it is well-documented
This may seem obvious but, if your code is not documented, then the only way to learn what it does is to reverse engineer it. Would you do that yourself? Let’s consider the extreme opposite and imagine if React, for example, had no documentation. Then there would be only few geeks to try this new tool from Facebook, since it would require browsing over the source code to understand what it does and how to use it. Of course there will be no businesses or enterprises using a non-documented library. What kind of CEO or CTO would want to risk their company’s resources on a technology that has unpredictable onboarding time? Moreover, it would be hard for Facebook’s engineers themselves to support and maintain the codebase, which makes a second point:
You will not be able to understand your code in 6 months
I bet you know the feeling when you look at the code that you have written a few months or years ago and can not understand a single line. It is even hard to admit the code was your creation. Sounds familiar? The code may even look like it was written by someone much less experienced and may seem silly, but still you are unable to explain what is going on there. Why did you write this?
At that moment an intense feeling of regret will creep in and you will start to realize the best moment to write a documentation was when you wrote the code, i.e. 6 months ago. Now, instead of reading the docs, you will have to read the code, and the code does not answer the question “why” it was written and does not explain itself. So the main purpose of documentation is to explain why you wrote this piece of software, including for yourself in the future.
Documentation is a love letter that you write to your future self.
– Damian Conway
Documentation makes the code better
You will have to think a lot about the design of your code when documenting it. Since you have to expose the whole structure of the code to the public, you will think twice about the way you built your project. Are there any parts to be refactored? Is there a way to implement some functionalities better or completely reorganize the code? So documentation process itself makes the code better.
What to write?
After it became clear how important documentation is, it seems that we can start creating one. However, before proceeding, I would recommend to stop for a while and do a step zero by clearly defining your target audience and understanding the value your project generates.
Define your audience
This one seems obvious but is often forgotten. It is better to clearly formalize who you are writing for. Who are your users? Are they mostly developers or designers? Experienced or fresh? Do they use your project in a large or small team? Etc, etc. Answering these questions will help you define an imaginary persona, which represents most of your users. Keeping this imaginary persona in mind will help you a lot, so the process of writing docs will look more like a dialog between you two.
What problem your project solves
The first thing to add to your document is a clear definition of what is the name of the project and what problem it solves. It is better to have one or two sentences. People are going to be visiting your page from many sources and, hence, have different perspectives. That’s why you have to be very precise and avoid vague descriptions. Simply state what your Javascript project is about, who it is for and what problem it solves. As an example of proper title and description, you can check out Sing App React Admin Template documentation.
Sing App React Admin Template documentation
Quick start and installation steps
Most people do not like to wait. So do your users. Let them launch and try your project as fast as you can. Prepare a simple short list of steps needed to setup the project and put it on top of documentation front page. Usually it may be a list of commands required to setup an environment and start the application. If it’s possible, it will be great to simply copy-paste these commands and have the entire application or library launched. Take a look at Rails Admin documentation as an example:
An example of quick setup steps
A list of steps needed to setup the library is clear and easy to execute, which makes the whole project more attractive to use.
Hopefully your users will be able to setup and launch everything, so now it is time to go a little bit deeper.
Components and features documentation
It is most likely that quick starting the project will not be the only option available to interact with it. There will be other parts, modules, components, features, classes, etc. You name it. E.g. pieces of your software that require separate documentation and provide an API to interact with it in some way.
The first thing to do is to list all of these components and make a table of contents based on it with links following to the relevant pages.
For every single piece of your documentation it is better to apply the same principle you apply to writing project description: name the component, describe what it is used for, what is the installation process, if there is one. What are the API methods and parameters, if so? Try to put yourself in a place of this imaginary persona you described earlier and imagine what would be the questions and difficulties integrating this particular component. Help them use it and leave no feature undocumented!
A list of steps needed to setup the library is clear and easy to execute, which makes the whole project more attractive to use.
Hopefully your users will be able to setup and launch everything, so now it is time to go a little bit deeper.
Components and features documentation
It is most likely that quick starting the project will not be the only option available to interact with it. There will be other parts, modules, components, features, classes, etc. You name it. E.g. pieces of your software that require separate documentation and provide an API to interact with it in some way.
The first thing to do is to list all of these components and make a table of contents based on it with links following to the relevant pages.
For every single piece of your documentation it is better to apply the same principle you apply to writing project description: name the component, describe what it is used for, what is the installation process, if there is one. What are the API methods and parameters, if so? Try to put yourself in a place of this imaginary persona you described earlier and imagine what would be the questions and difficulties integrating this particular component. Help them use it and leave no feature undocumented!
Firebase documentation. Table of contents and single component parts are clearly visible.
Firebase documentation is a great example of structuring docs. You can see the menu of all available documentation parts on the left side and interact with particular component in the middle of the page.
License and contribution instructions
There must be something that guides relations between your project and its users. You have to decide under what conditions your software is distributed and can be used. There are lots of standard licenses available around the web, so it is up to you to pick the right one for your project. The most popular ones are: BSD, MIT, Apache GNU licenses. They are open source, so keep that in mind. Proprietary licenses vary a lot from project to project, so this can be a separate topic.
If your project is open source then you are expecting people to contribute. Hence it will be very helpful for them to have some sort of guidance from you. Let them know where they can report issues, ask questions, what are the restrictions or prior assumption before contributing, where they can find issues, etc. Otherwise you are about to lose a great amount of thankful supporters and maintainers.
Tips on writing documentation
We will not be able to predict all the use cases and the way users will use your documentation. In general it is a great principle to keep imagining yourself as your user and organize everything based on this point of view. However, here is a short list of general tips every project documentation must follow:
People will simply copy and paste your code. Keep this in mind and make sure to double check this yourself by executing it. Avoid placing some invisible characters to code examples. It is even better to use code and blockquote tags to embed code blocks.
Keep your documentation updated. Every change in code must be followed by a relevant change in documentation. Otherwise documentation soon becomes outdated, which is equal to the absence of documentation.
Code comments are a part of documentation. This is the last and very important one. If your project is open source, users are going to be reading through your code, hence inline comments will help them a lot. Furthermore, there are tools like JSDoc that generate documentation based on code comments! So you do not have to write anything in a separate file. Simply feed this tool with your codebase and, voila, you have the documentation.
Tools to speed up the process
Why would you want to write and create everything from scratch and by yourself if there are so many documentation tools available? Nowadays generating documentation, especially if you produce high-quality code with inline comments, is a matter of running a single command.
So let’s overview documentation tools available in 2019.
JSDoc is the most popular Javascript documentation generator. All you need to do is to simply run jsdoc command with a filename as an argument. That is it. It will generate HTML file with documentation that is ready to use. The website is https://github.com/jsdoc/jsdoc.
Docusaurus is a more complex tool that allows you to generate entire documentation website based on markdown files with documentation contents. It is based on React and supports versioning, so you can easily maintain different versions of the documentation generated in the past. Other great benefits are embedded search and multi language support, which is crucial for popular repositories. The website is https://docusaurus.io/.
apiDoc creates a documentation from API annotations in your source code. It is a great tool to generate a documentation for a project that has and exposes lots of API methods. It allows to customize everything a lot, e.g. specify parameters, error codes, response samples, etc. The website is http://apidocjs.com/
Great examples of JavaScript project documentation
When creating something new it is good to have some sort of example, something you can refer to. So here is the list of various projects you may get your inspiration from. All of them are great, so pick one you like the most.
I hope that you found this article useful and it will help you a lot when creating documentation for your javascript project. Googling the Internet tells that documentation is a key to success in any Javascript project, and I strongly agree with this rule. Documentation is sort of a facade that people face and resort to when using your project. So always keep it updated and put yourself in place of your users!
If you like our articles, this might be interesting too:
