<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Adam Janes on Medium]]></title>
        <description><![CDATA[Stories by Adam Janes on Medium]]></description>
        <link>https://medium.com/@adamjanes?source=rss-afd2b6706aa7------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*i88DrX2q0W92jZPc3isGVw.jpeg</url>
            <title>Stories by Adam Janes on Medium</title>
            <link>https://medium.com/@adamjanes?source=rss-afd2b6706aa7------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 02:20:55 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@adamjanes/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[My (Our) Social Project Manifesto]]></title>
            <link>https://medium.com/oursocialproject/my-our-social-project-manifesto-66963e48fe0b?source=rss-afd2b6706aa7------2</link>
            <guid isPermaLink="false">https://medium.com/p/66963e48fe0b</guid>
            <category><![CDATA[self-improvement]]></category>
            <category><![CDATA[friendship]]></category>
            <category><![CDATA[life-lessons]]></category>
            <category><![CDATA[community]]></category>
            <dc:creator><![CDATA[Adam Janes]]></dc:creator>
            <pubDate>Sun, 27 Jan 2019 15:51:40 GMT</pubDate>
            <atom:updated>2019-01-27T15:51:40.265Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YTy2qo2cBW92EiXUhHV0Bw.png" /></figure><p>It’s a simple truth to recognize that we have everything that we need to be happy in this world. The tragedy is that we spend most of our lives lost in an unconscious state, entirely at the mercy of whichever thought next comes barreling into our consciousness. We are almost always preoccupied by anxiety about something that we just did, blame at something that we just thought, or concern for something that might happen in the near future.</p><p>More than anything else, we are confronted with a constant sense of shame. Our society doesn’t accept us as we are, and we don’t accept ourselves as we are. We feel guilty about who we are, what we look like, what we did, or what we think. And then we feel guilty for beating ourselves up about it.</p><p>On closer inspection, you might think that this state of mind isn’t consistent with the facts of the universe that we live in. Although we have a conception of ourselves as these separate egos — as if we somehow represent own loci of causality in the world, deciding all our actions by ourselves— our consciousness is really just a series of flashes. A thought pops into our head, that sparks a chain reaction of related thoughts. An emotion washes over us, and we become lost in it. We feel the pang on our cheeks at a sudden cold burst of wind. We take in inputs, and it impacts how we live our lives. There’s nothing that remains of ourselves that makes sense to feel ashamed of.</p><p>We can see this for ourselves on a visceral level if we turn our attention inwards — to examine our moment-to-moment experience of the world.</p><p>How can we live in a state where we can see the world for what it really is? What can we do to break out of this illusion? How can we truly learn to just be happy?</p><p>When I first moved to Berlin last April, I often felt overwhelmed by a sense of loneliness. There was a sort of self-shaming going on inside my head, where I felt bad about the fact that I didn’t have anyone to hang out with. I’d typically have a few different friends who I could meet up with for a beer or something, but I didn’t have a proper sense of community. What made things worse is that Berliners are renowned for their flakiness. It’s not hard to take a last-minute cancellation personally — as if everyone just isn’t all that jazzed to see you.</p><p>I’d find myself alone on a Friday or Saturday night. The typical circle of thoughts that would run around my head went something like this:</p><ul><li>“You’re living in a fun, awesome city like Berlin — where everyone else is having fun with friends — but you’re all alone.”</li><li>“You’re such a loser. Nobody thinks you’re interesting enough to hang out with.”</li><li>“If you weren’t so neurotic, then people would want to hang out with you.”</li><li>“Because nobody likes you, you won’t be able to pull yourself out of this rut. What if this is just the way your life is now?”</li></ul><p>This went on until October, when something happened. I went to a hackathon with a group of friends that I used to live with in Bangkok, where we had a built a vibrant community together. These people all shared the same type of questioning, scheming, entrepreneurial mentality as me. They too were disillusioned with the kind of dog-eat-dog consulting/finance lifestyle that so many of our peers had fallen into. We wanted to do something special with our lives, without sacrificing ourselves to do it. We were all lost souls in our own little way — and we were all searching for answers to what we wanted to do with our lives.</p><p>As a bit of context, these two friends at the hackathon are both a little eccentric. They’re big believers in personality testing. They believed in using psychological indicators such as MBTI results to influence how you should treat different people. They used to run a startup trying to match people into friendship groups, based on their personality type. I had met them in my first week in Bangkok, at a party that they were hosting as a way to build traction for this brand, and we hit it off immediately. We would go on to live together in a house of 7 expats, who were selected because they had the exact same personality type. It was pretty weird, but I loved it.</p><p>What happened that weekend in October completely saved me. I had a feeling of being unconditionally accepted, part of a group, for the first time since I’d moved to Berlin. We had a community that meant something to all of us, and we actively made the effort to make sure that every member of the group was looked after. For that weekend, I felt like I had all the energy in the world. Creative thoughts were constantly pouring into my head. As I grew more secure in myself, I noticed that I started to develop a genuine desire to start to help other people too. My overall view of the world shifted from one of antagonism — “Everyone out there is trying to screw me over.” — to one of compassion — “Anyone who might try to screw me over, is tragically cursed with problems of their own. I should try to help them to feel better, so that they wouldn’t need to act this way.”</p><p>When I came back to Berlin, nothing had really changed with my life situation. I still had a collection of friends that I would bump into every now and then for a beer. Some nights, I would still find myself sat at home on a Friday night, when I’d really rather be doing something else, but it wouldn’t affect me in the same way. I didn’t feel the same sense of insecurity anymore. Whether I was either part of a group or alone at this particular point in time, I still had a feeling of that I was worthy of real friendship. It felt inconceivable to me that I could be unworthy of human connection, after being part of a community like that so recently.</p><p>Around this kind of time, I had been reading a few different books that really colored my thinking. One book which I absolutely loved was <em>The Culture Code </em>by Daniel Coyle, which came out recently in 2018. It’s all about how businesses can craft great team cultures. In some companies, employees are excited to come to work everyday, they feel like they’re part of something bigger than themselves, and they describe their coworkers with a touching word — <em>family</em>. The basic lesson of the book is that we should strive to create a judgement-free environment, where people feel like part of a group, and where they’re safe to try things out without any danger of being shamed by others.</p><p>A culture like this, Coyle argues, is built by sending out “belonging cues” — little nudges to display that we think that members in our group are in our team. These cues could be as simple as maintaining eye contact, being physically close to one another, making sure that we give everyone a chance to pitch into the conversation, and showing that we genuinely care about their point of view.</p><p>Another part of this formula involves openly sharing our vulnerabilities. The idea is that, if we can search for moments where we can share our worries and insecurities, we get to a deeper level of connection with one another. Rather than acting as if we’re completely perfect — and hiding all of the shame and self-hate sloshing around inside of us — we admit that we’re all human, deep down at heart, and that we all share in these kinds of neuroses together. A positive side-effect by doing this is that we make the vibe more comfortable for others to share insecurities for themselves.</p><p>At the same time, I had been reading all sorts of different parenting books (it’s a bit of a weird story why — I don’t have a kid). I found some great advice about how parents can engender healthy emotional attitudes in their children, which really resonated with me.</p><p>There were a couple of concepts that I found particularly useful.</p><p>One concept that I like is being accepting to your child’s feelings as they are. A child might say “I hate grandma!”, and the mother’s gut reaction might be to shoot back with, <em>“How dare you say that! Of course you don’t hate grandma!”</em>. The lessons that the child learns through this kind of interaction are:</p><ol><li>“I don’t really feel the way that I think I feel. Therefore, my emotions are to be mistrusted.”</li><li>“Some of my feelings are so shameful, that they shouldn’t be shared with anyone else. I need to bury certain kinds of feelings deep down in the back of my mind. I should feel pretty bad if they ever pop up again by themselves.”</li></ol><p>As much as the mother might wish that her child didn’t hate her grandma, that doesn’t change how she feels in her heart of hearts.</p><p>Good parenting, then, is all about trying to create an attitude of acceptance of the thoughts that children have, and treat them as they are — just thoughts. If we bring our children up in that world, then they’ll cease to carry this kind of mentality of shame around with them for the rest of their life — and they can start to be happy.</p><p>Another interesting concept in parenting is the idea of attachment theory. The idea is that, depending on how a child is raised, they will inherit a certain kind of “attachment style” that dictates how they react to others for the rest of their lives.</p><p>For example, if a child needs something, and cries out to their parents, if the child’s needs are consistently met, then they will grow up to become <em>securely attached</em>. There is no fear within them that one day they might suddenly have nobody to look after them. They don’t have any sort of lingering paranoia about whether their parents will truly be there for them. As a result, if they ever find themselves without anyone to care for them, they don’t worry. They are used to the idea that they are inherently deserving of love, and there’s no need to stress about it.</p><p>On the other hand, if a child cries out, and finds their needs to be met only some of the time, then they will grow up to be <em>weakly attached</em>. They live with a constant sense of doubt about whether or not anyone will be there for them. When these children grow up, they love in an incredibly needy way. When somebody gives them attention, they crave it like a drug, because they never know when they’ll be able to get their next hit of it.</p><p>The final variation here is that, if a child’s needs are consistently <em>never</em> met, then they will become <em>unattached</em> — they won’t expect love from people at all, and they might even just accept that they are completely undeserving of it.</p><p>Good parenting, therefore, can be seen as keeping kids’ <em>“attachment cup”</em> full. They need constant affirmation of a parent’s love — and conflicts need to be resolved with reconnection.</p><p>This is also something that gets talked about in <em>The Culture Code</em>. Human beings aren’t evolved to take mere words to heart — it has to be constantly re-affirmed. It’s not enough to tell your partner that you love them — this needs to be done consistently everyday, otherwise we start to worry, and we start to forget.</p><p>It occurred to me how directly relevant all of this new material had been for my experience as part of a community. After a time, lacking a proper group connection in Berlin, my cup was empty. My thoughts were completely taken up by a sense of shame for who I was and what I was thinking. This state colored my experience of the world, and as that happened, I started to tense up, and see people less charitably. When my cup was full again — when I felt like I belonged to a group that accepted me no matter what — I suddenly had the power and the energy to grow to work on myself, and soon, I naturally wanted better things for other people too.</p><p>I came across a lovely story recently:</p><blockquote>As the 21st century was beginning, a South African psychiatrist named Derek Summerfield happened to be in Cambodia conducting some research on the psychological effects of unexploded land mines — at a time when chemical antidepressants were first being marketed in the country.</blockquote><blockquote>The local doctors didn’t know much about these drugs, so they asked Summerfield to explain them. When he finished, they explained that they didn’t need these new chemicals — because they already had antidepressants. Puzzled, Summerfield asked them to explain, expecting that they were going to tell him about some local herbal remedy. Instead, they told him about something quite different.</blockquote><blockquote>The doctors told Summerfield a story about a farmer they had treated. He worked in the water-logged rice fields, and one day he stepped on a land mine and his leg was blasted off. He was fitted with an artificial limb, and in time he went back to work. But it’s very painful to work when your artificial limb is underwater, and returning to the scene of his trauma must have made him highly anxious. The farmer became deeply depressed.</blockquote><blockquote>So the doctors and his neighbors sat with this man and talked through his life and his troubles. They realized that even with his new artificial limb, his old job — working in the paddies — was just too difficult, that he was constantly stressed and in physical pain, and that these things combined to make him want to just stop living. His interlocutors had an idea.</blockquote><blockquote>They suggested that he work as a dairy farmer, a job that would place less painful stress on his false leg and produce fewer disturbing memories. They believed he was perfectly capable of making the switch. So they bought him a cow. In the months and years that followed, his life changed. His depression, once profound, lifted. The Cambodian doctors told Summerfield: “You see, doctor, the cow was an analgesic, and antidepressant.”</blockquote><blockquote>— Johann Hari</blockquote><p>In the context of self-help literature, the assumption tends to be made that we must first develop a sense of self-esteem, and that will make us worthy of human connection. If we could only force ourselves to treat ourselves with acceptance, then other people will like us too. We need to do this if we want to find a better job, improve our relationships with friends, or find our one true love.</p><p>I’ve started to wonder lately if we’ve gotten it the wrong way around. What if first we need the human connection, and then we have what it takes to find our self-esteem?</p><p>What if we could design a structure for a new type of group friendship — one predicated on support, compassion, and acceptance? What would be possible in a world where everyone was part of a group like that? How much energy would people have to change themselves for the better; to do what’s right for themselves, for their friends — maybe even for the whole world? How would we do that?</p><p>I think that a key component would need to involve the use of rituals, to turn our day-to-day routines into something that improves us for the better.</p><p>I once took a fantastic class at university on Chinese philosophy, where this was stressed to a monumental degree. It all starts with the Analects — a compilation of statements by/about Confucius, put together by his followers after his death. Western philosophers tend to view Confucius as a sort of extreme conservative. He would value practices such as submissively paying reverence to your parents, without any particular justification. Indeed, reading the Analects on a surface level might seem confusing. It’s full of random statements like “Confucius said X…”, and “One day, Confucius did this…” — all without any cohesive theme. Sometimes, these stories would even contradict themselves. Confucius would condone an action in one chapter, then say the exact opposite somewhere else. It’s also filled with seemingly irrelevant information, that doesn’t appear to be an allegory for anything deeper. There’s even a verse that talks about how Confucius straightened his mat every morning in a particular way!</p><p>In reality, Confucius was deeply interested in the power of rituals, and the Analects pays homage to how a great man worked this commitment into his daily life. What is a ritual? It’s a pattern of behaviour that we establish as a society which, when done right, should teach people to improve themselves.</p><p>For example, imagine that you’re walking about around town one day, and you clock a friend about 50 meters ahead of you. You both see each other. You gradually approach. You look down. When you are about 5 meters apart, you both look up, awkwardly give each other a wave, mumble, <em>“hey… how’s it going?…”</em>, and keep walking.</p><p>Why do we do this? Because it’s the only way to be normal. Society has thrust this obligation onto us, and at this point, it would be simply too weird not to play by social convention. What we have here is a ritual. A ritual that we perform badly. A ritual that we perform badly, which we’ve forgotten the point of. A ritual that we perform badly, which we’ve forgotten the point of, and that we still continue to do anyway.</p><p>What would it look like if we managed to do this ritual the <em>right way</em>? Why do we even say, <em>“hey… how’s it going?…”</em> at all?</p><p>At some point, when this convention was first established, you might think that it came out of a place of care for the person that you’ve just bumped into. You want to know how they’re doing, and you’re going to try to impact the trajectory of their day for the better as a result of this interaction. When viewed like this, every chance encounter that we make could be an opportunity to make the world a better place.</p><p>If there is a world that we can live in, where we refuse to let these kinds of rituals be performed badly, then what would this look like? How would you try to make somebody’s life better, if you could, by a simple, <em>“hey… how’s it going?…”</em> done right?</p><p>If you try this ritual for yourself, you might soon realize that you don’t quite have the social skill to do this well. For one thing, you might misread the mood that your friend is in on a particular day. If somebody is in a rush, then they might not want to be apprehended, and coerced in a long conversation about their feelings! Your friend might not have been raised in an environment where they feel comfortable talking about their problems, so this might make them uncomfortable. You might even just lack the level of mindfulness to regularly pull yourself out of your own barrage of thoughts, to say something that inspires true connection.</p><p>For Confucius, a ritual that is done well should help us to develop the sensibility to be able to tailor our actions to different circumstances.</p><p>Maybe the first time you try this out, it comes across as a bit weird. The encounter might go something like this:</p><blockquote>You: [Super enthusiastically] Hey!!! How’s it going!!!???</blockquote><blockquote>Friend: [Looking glum] Hey… Uhhh… Not bad… How are you?</blockquote><blockquote>You: I’m not too bad at all! But I really wanna help you feel better with this interaction. Are you sure that you’re feeling “not bad”? Is there anything going on with your life that’s bothering you?</blockquote><blockquote>Friend: [Weirded out] Uhhh… No, I’m fine… Really…</blockquote><blockquote>You: Okay… If you say so…. Have a nice day!</blockquote><p>This interaction could have gone better. You were a bit too obvious, and a bit too weird for this friend at this particular time. They didn’t open up to you, because you seemed too outlandish to be taken seriously.</p><p>Not to worry. Next time, you’ll do things differently. If every time that you perform this ritual, you do a little bit better, and if every <em>“hey… how’s it going?…”</em> becomes an opportunity to improve, then soon enough, you will manage to go deeper with it every time.</p><p>Eventually, the dialogue might look something like this:</p><blockquote>You: [Warm and sincere] Hey! How’s it going?</blockquote><blockquote>Friend: [By default] Hey… Not bad…</blockquote><blockquote>You: [With a genuine interest] No, really… How is it going? You look a little off today.</blockquote><blockquote>Friend: Well, yeah… I mean things have been a little rough lately. Things aren’t going too well with my girlfriend at the moment, and I’m really swamped with work.</blockquote><blockquote>You: I’m really sorry to hear that. I know how that feels, and it’s never an easy process. In truth, I struggled for quite a long time myself a few months ago. Do you think it’ll be okay?</blockquote><blockquote>Friend: [Relieved] Well, yeah, I mean, I think it’ll all be fine. The project that I’m working on right now is really tough, but I’m optimistic that things’ll look up in a few weeks’ time. And I think that everything will be fine with my girlfriend. We do really love each other, after all.</blockquote><blockquote>You: I’m glad to hear that. It’s never easy going through a rough patch like this. You know, I’m always there for you if you need me, and if you ever need to talk about this stuff, I’m all ears.</blockquote><blockquote>Friend: Thanks buddy. That really means a lot to me.</blockquote><p>In Confucian terms, there is a word for somebody who reaches this kind of mastery — <em>a sage</em>. A sage can judge the environment that they find themselves in, tailoring their actions perfectly to match the mood of those that surround them. As if by magic, as they float along through the world, their calm and positive demeanour becomes infectious. Step by step, they lift up those around them, and bring them to a new level of being.</p><p>So, on a practical level, what should an ideal community look like, and how might it work?</p><p><em>How about this for a dopey idea…</em></p><p>A group of 3 or 4 friends commit to establishing a powerful community. The goal is to get to a place where we truly connect with each other. We agree to treat each other with the sort of care that we would reserve for one of our children. We fill up each others’ cups.</p><p>We make sure that we all feel accepting enough of our own state of mind, and that we don’t need to live in a constant state of shame. In this state of comfort, we start to grow. We share advice, books, and resources, giving ourselves the knowledge to help each other in every area of our lives.</p><p>We create rituals that reinforce this sense of community. We constantly give out <em>belonging cues</em>, share vulnerability, and take every interaction as an opportunity to practice. We start to feel better. We actually start to feel great. We start to care about other people more. We unleash a positive feedback loop, where we become more engaged in our own rituals, as we see the effect that they have on ourselves, and on others.</p><p>After a while, we start to bring others in. We attend an event as a group, and start talking to strangers. We subtly invite them into our conversation circle. We expertly dish out a flurry of loving statements that make them feel at one with the world, for the first time in a long while. They become completely enamoured by us. They notice how they feel when they’re in our company. They suddenly feel like they can do anything.</p><p>At some point, they start to notice the weird little quirks with how we interact with each other. We might decide on a ritual that says that we should give each other a hug whenever we greet each other. This might not be a normal hug. This might be a hug where we enforce a real sense of presence to the moment. We might insist that this hug should mean something — that it be a genuine expression of gratitude that a friend exists in our life. The strangers, if they don’t immediately find it to be <em>just way too weird</em>, might want to get involved with this.</p><p>“Why do you guys do that?” — they might ask. We might explain our reasoning, and they might like where we’re coming from. They might want to join our social project themselves. They might have their own creative ideas for rituals that we could do to bring the group together. They might want to help to spread this message even further. They might organize a barbecue, which is open to everyone, or they might throw a party at their house.</p><p>Alternatively, they might think it’s super weird. They might think that we look a bit like a cult, or worry that we might try to convert them to some weird religion. If that’s the case, then we might try to make our rituals a little less intense the next time we go to one of these events. We might take every event that we attend as an opportunity to do better and, eventually, it might actually work.</p><p>One day, 5 years from now, there might be a million people acting like this. People might organize themselves into decentralized groups — gathering regularly all around the world — spreading the gospel of human connection. We might all be excited to try to make the world a better place.</p><p>Imagine what kind of world that might be.</p><p>We could have gone another way with this. We could have decided to preach to people, in very logical terms, that there is a better reality that they could live in, if only they gave it a proper try. We might say that they ought to read 10 books that would give them the a theoretical understanding of why this makes sense. We might alienate people with abstract notions of <em>“belonging cues”</em>, <em>“attachment theory”</em>, and <em>“rituals”</em>. They might not think it’s worth the hassle.</p><p>We could also have wrapped these ideas into a company, charging a high fee for the potentially life-changing effect that this kind of community might bring them. You tend to see this a lot with “self help” people. “Gurus” and “life coaches” will charge you $4,000 for a week-long workshop to build your self esteem. It might even be worth the money if you take it seriously enough.</p><p>I think that this distorts the pure intention that they claims to motivate their actions. It immediately alienates large swathes of people, and it sows the seeds for a general feeling of mistrust.</p><p>I’d like to treat this as an open source project. I want to say that, rather than pursuing this out of a need for personal gain, we should try to leave a lasting impact on the world. Like the development of the Internet, Wikipedia, or Linux, I want us to come together to give something positive back to the world around us.</p><p>Ultimately, a true gift made by a friend should never come at a cost.</p><p>As a kick-off for this project, I’m starting off with a super simple framework. I’ve made a <a href="https://github.com/OurSocialProject/OurSocialProject">GitHub page</a> for a new open source initiative — <em>OurSocialProject</em>. In true <em>open source style</em>, this will all work through Git, a version control system that we programmers tend to use. I’ve come up with a rough mission statement, a set of values that I think this community should live by, and some example rituals that I want us to try out. For now, I imagine that I’m missing a lot of obvious stuff.</p><p>Everyone is encouraged to fork (make a copy of) this repository for themselves, and do whatever they want with it. I want us all to start out by creating our own <em>“My (Our) Social Project Manifesto”,</em> which will be helpful to structure our own thoughts about what good community means. If you feel comfortable with it, then you can even share your manifesto on Medium, and we can feature it here on the <em>OurSocialProject</em> channel. You can either take my mission statement, values, and rituals as your own, or you can tweak them to fit with your own ideas.</p><p>Once we have all of this set up, then we can sort ourselves into local hubs of action. I’d like to be as flexible with this as possible. You might decide to club together with an existing group of friends, making a conscious decision to approach your community with a greater sense of intention. Alternatively, you could <a href="https://join.slack.com/t/oursocialproject/shared_invite/enQtNTMwNDE4Mjk5NzMwLWEzMjg4MmYxYTdhZGJmNzdkMWY4YWE4MGQwMzdkZGRkODAzN2YyNzVkMDAxMGZhOTJkNzkxYzkzZjdlNWY1ZGQ">join the <em>OurSocialProject</em> Slack channel</a>, and look for a group of people in your local area. You might even decide to share your own <em>My (Our) Social Project Manifesto</em> here, to give an opportunity to show these new people what you’re all about!</p><p>You can meet up with these people, and see if you can forge a better human connection with them. You might find a really cool <em>Meetup</em> event that you might want to attend. You might go to an art gallery opening that looks interesting. You might even just go to the pub for a pint. Either way, make it weird, and see if you can see any benefits for yourself. Maybe you’ll have a good time, or maybe it’ll bore you to death. But hopefully, after a few tries at getting better, you‘ll find some strategies that work for you.</p><p>If you end up doing this for yourself, then I would be curious to see how you get on. Which rituals did you find the most enticing? How did everyone feel about it? Was it an awkward thing to do? Would you do it again?</p><p>I’m extremely self-aware in realizing how cultish, wacky, and just plain weird this whole concept is. In actual fact, I’ve tried to design it to be that way. I want to see a world where only the people who take these concepts seriously will actually try to put them into practice.</p><p>If you don’t have a technical background, it can see like quite a faff to go through the effort of forking the repository, editing the README, and writing a whole manifesto (especially if it’s as long and waffley as this one!). I’m also encouraging you to be bold with this. It’s really a lot of effort to jump through this many hoops, and to share things about you like this in such an open and vulnerable way.</p><p>My hope is that, if only a few people are excited enough by this project to do this, then those people will be great friends to have as part of a local community. If only a few groups actually latch onto this, and make this a priority, then we can already have a huge impact. Over time, as more and more contributors get involved, we might make a more mainstream version. But saying that, I’d still encourage you to get involved now if this sounds like a project for you.</p><p><a href="https://join.slack.com/t/oursocialproject/shared_invite/enQtNTMwNDE4Mjk5NzMwLWEzMjg4MmYxYTdhZGJmNzdkMWY4YWE4MGQwMzdkZGRkODAzN2YyNzVkMDAxMGZhOTJkNzkxYzkzZjdlNWY1ZGQ">Join our Slack community.</a></p><p><a href="https://github.com/OurSocialProject/OurSocialProject">Fork me on GitHub.</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=66963e48fe0b" width="1" height="1" alt=""><hr><p><a href="https://medium.com/oursocialproject/my-our-social-project-manifesto-66963e48fe0b">My (Our) Social Project Manifesto</a> was originally published in <a href="https://medium.com/oursocialproject">OurSocialProject</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[5 crucial concepts for learning d3.js and how to understand them]]></title>
            <link>https://medium.com/@adamjanes/5-crucial-concepts-for-learning-d3-8ca460f18787?source=rss-afd2b6706aa7------2</link>
            <guid isPermaLink="false">https://medium.com/p/8ca460f18787</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[data-visualization]]></category>
            <category><![CDATA[d3]]></category>
            <category><![CDATA[web-development]]></category>
            <dc:creator><![CDATA[Adam Janes]]></dc:creator>
            <pubDate>Mon, 19 Mar 2018 04:36:40 GMT</pubDate>
            <atom:updated>2018-03-20T04:57:45.303Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IEwZ5DJLCPmoHPieqTCsdg.png" /></figure><h3>5 crucial concepts for learning D3.js and how to understand them</h3><p>You may have already heard about <strong>d3.js</strong>, the dazzling JavaScript library that lets you create beautiful charts and graphics with just a few lines of code. You might have seen some of the <a href="https://github.com/d3/d3/wiki/Gallery">fantastic examples</a> of D3 in action, or you may have heard that the New York Times uses it to create its <a href="https://www.nytimes.com/interactive/2017/12/21/us/2017-year-in-graphics.html">interactive visual stories</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*bUt7ld9910qVUSoMw4YsXA.png" /></figure><p>If you’ve ever tried to dip your feet into the world of D3, then you’ll already be familiar with its <strong>famously steep learning curve</strong>.</p><p>You just don’t get to build things right out of the box with D3.</p><p>With its confusing method chains, alien syntax, and black-box functions that seem to work by magic, D3 can quickly seem like more hassle than it’s worth. But fear not, because D3 gets substantially easier if you understand just a few key concepts.</p><p>I want to take you through a simple tutorial, explaining 5 of the most common areas of confusion that beginners face when starting out with D3.</p><p>We’re going to create a dynamic scatter plot, which updates every second between two different sets of data:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4jWVP5cKEbrKONacMmLWOA.gif" /></figure><p>Take a moment to appreciate the little details here. Check out how smoothly these dots are sliding across the screen. Look at how they fade gently in and out of view. Behold the calm sway of our axes between their different values.</p><p>These are actually some of the easiest features to implement in D3. Once you can get through the initial struggle of figuring out the basic building blocks of the library, adding in this kind of stuff is a piece of cake.</p><p>Before we get ahead of ourselves, let’s talk about what D3 actually is.</p><p>D3 stands for <strong>Data Driven Documents</strong>.</p><p>The <strong>data</strong> can be absolutely anything, which is part of what makes D3 so powerful. Most of the time in D3, you’ll want to read in this data from a file, but for this example we’ll just be using two arrays stored as variables:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/36248030961c8d2936aa3f0bd945ec53/href">https://medium.com/media/36248030961c8d2936aa3f0bd945ec53/href</a></iframe><p>The <strong>documents</strong> part in D3 refers to the Document Object Model (DOM). D3 is all about moving elements on the page around, based on what the data is saying. Specifically, we’re working with special shape elements called SVGs.</p><h4><strong>Crucial Concept #1 — Working with SVGs</strong></h4><p>So here we come to the first challenging concept that every D3 newbie has to deal with. You immediately need to get a good grasp on a special type of markup which you might not have seen before.</p><p>Here’s what SVG markup might look like:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/abedb4070ff73d023fe63b3ec1c04c84/href">https://medium.com/media/abedb4070ff73d023fe63b3ec1c04c84/href</a></iframe><p>If we place this snippet into an HTML document, then our browser will interpret it like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gmFqaLYLeCNTMx7La8UJjA.png" /></figure><p>Basically, each of these SVGs has a set of attributes which our browser uses to place these shapes on the screen. A few things to know about SVGs:</p><ul><li>There’s a distinction between the SVG canvas (drawn with the &lt;canvas&gt; tags) and the SVGs shapes themselves.</li><li>There’s a fairly unintuitive coordinate system that you’ll need to understand, since the (0, 0) point of an SVG grid is at the top-left, rather than the bottom-left.</li><li>You might come across some pretty weird behavior if you don’t understand what’s going on under the hood.</li></ul><p>It can be tempting to gloss over this subject, opting instead to dive head-first into the titillating business of laying down some D3 code right away, but things will seem a lot clearer later on if you know how these shapes are working.</p><p>Resources for understanding SVGs…</p><ul><li><a href="http://unicorn-ui.com/blog/svg-for-beginners.html">A guide to SVGs for absolute beginners — Rob Levin</a></li><li><a href="http://alignedleft.com/tutorials/d3/an-svg-primer">An SVG primer for D3 — Scott Murray</a></li></ul><p>As a first step to building our scatter plot, we’ll want to add a small circle SVG for each item of data that we want to display. We add SVGs in D3 like this:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/8b8dba44777fb3eef6be654069e83838/href">https://medium.com/media/8b8dba44777fb3eef6be654069e83838/href</a></iframe><p>Writing <em>d3.select(“#canvas”)</em> here is analogous to writing <em>$(“#canvas”)</em> in jQuery, as it grabs hold of the element with the ID of “canvas”. <em>d3.select</em> goes one step further, adding a few special methods to this selection that we’ll be using later on.</p><p>We’re using the <em>d3.append</em> method to add a circle SVG to that element, and we’re setting each of the circle’s attributes with the <em>d3.attr</em> method.</p><p>Since we want to add a circle for every item in our array, you might think that we’d want to use a for loop:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3fecb0b2362d3bc29067b962505551f4/href">https://medium.com/media/3fecb0b2362d3bc29067b962505551f4/href</a></iframe><p>However, since this is D3, we’ll be doing something slightly more complicated, and slightly more powerful…</p><h4><strong>Crucial Concept #2 — Data Binding</strong></h4><p>The next hurdle that every new D3 developer needs to overcome is the D3 data join. D3 has its own special way of binding data to our SVGs.</p><p>Here’s how we add a circle for every item in our array with D3:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/834c1f63869a6276d4c2c99e1badf1fb/href">https://medium.com/media/834c1f63869a6276d4c2c99e1badf1fb/href</a></iframe><p>For a developer who is just starting off with D3, this can seem confusing. Actually, for many seasoned developers with years of experience in D3, this can still seem confusing…</p><p>You would think that calling selectAll(“circle”) on a page devoid of circles would return a selection of nothing. We’re then calling the data() method on this selection of nothing, passing in our array. We have a mysterious call to the enter() method, and then we have a similar setup as before.</p><p>This block of code adds a circle for each item in our array, allowing us to set our attributes with anonymous functions. The first argument to these functions gives us access to the item in our data that we’re looking at, and the second argument gives us the item’s index in our array.</p><p>Creating a “data join” like this marks the first step to doing something useful with our data, so it’s an important step to understand. This strange syntax can be daunting when you first encounter it, but it’s a handy tool to know how to use.</p><p>Resources for understanding data binding in D3:</p><ul><li><a href="https://www.sitepoint.com/a-beginners-guide-to-data-binding-in-d3-js/">A beginner’s guide to data binding — SitePoint</a></li><li><a href="https://bost.ocks.org/mike/join/">Thinking with joins — Mike Bostock</a></li><li><a href="http://www.cagrimmett.com/til/2016/08/17/d3-lets-make-a-grid.html">Let’s make a grid with D3.js — Chuck Grimmett</a></li></ul><p>Once we run the code that we’ve written so far, we end up with something that looks like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/715/1*tXJRw9qml6Dd0WKcksXRxA.png" /></figure><p>We attached the right number of circles to the screen and spaced them out a little, but what we have so far isn’t particularly helpful. For a scatter plot, the coordinates of these circles should correspond to two different values.</p><p>The GPA and height values that we have in our arrays aren’t much use to us at the moment. Our GPA values range from 2.32 to 3.85, and our height values range from 138 to 180. When positioning our circles, we want to work with x-values between 0 and 800 (the width of our SVG), and y-values between 0 and 500 (the height of our SVG).</p><p>We’ll need to apply some kind of transformation to our raw data, to convert these values into a format that we can use.</p><p>In D3, we do this by using scales.</p><h4><strong>Crucial Concept #3 — Scales</strong></h4><p>Here comes our next major challenge to picking up D3.</p><p>Scales are confusing to talk about when you’re first getting started. They need to be set with a <strong>domain</strong> and a <strong>range</strong>, which can be pretty easy to confuse. The <strong>domain</strong> represents the interval that our <strong>input values</strong> will run between, and the <strong>range</strong> represents the interval that our <strong>output values</strong> will run between.</p><p>A scale is a function in D3 that will take in a value as an input, and spit out a different value as an output. In this example, we’ll need an x-scale that converts a GPA to a pixel value, and a y-scale that converts a person’s height to a pixel value, so that we can use our data to set the attributes of our circles.</p><p>Here’s a diagram to show you what our x-scale should be doing:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/748/1*rOQ0kNlE8BYWEn_vri-50Q.png" /></figure><p>We need to initialize our domain and range with some minimum and maximum values. We’re saying that a value of 3.54 should translate to a pixel value of 800, and a GPA of 2.76 should translate to a pixel value of 0. So, if we pass in a value of 3.15 to our scale, then the output would be 400, since 3.15 is half way between the min and max of our domain.</p><p>In this example, we’re using a linear scale, meaning that values should be scaled proportionally between the two extremes that we’re looking at. However, there are a few different types of scales that you’ll want to get your head around.</p><ul><li>If you’re working with data that increases exponentially over time, then you might want to use a <strong>logarithmic scale</strong>.</li><li>If you’re working with date values, then you’ll use a <strong>time scale</strong>.</li><li>If you want to assign colors between different categories, you can use an <strong>ordinal scale</strong>.</li><li>If you’re spacing out rectangles in a bar chart, then you’ll use a <strong>band scale</strong>.</li></ul><p>For each of these scales, the syntax is slightly different, but it’ll still follow the same general format as our linear scale.</p><p>Resources for understanding scales in D3…</p><ul><li><a href="https://benclinkinbeard.com/posts/introduction-to-d3-scales/">An introduction to linear scales in D3 — Ben Clikinbeard</a></li><li><a href="http://d3indepth.com/scales/">A walkthrough of the different types of scales — D3 in depth</a></li><li><a href="https://github.com/d3/d3-scale">The entry for scales in the D3 API reference</a></li></ul><p>So now, we can add in two linear scales to use for our x and y axes.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/c8e57594a5464f10669ace359d7ec97b/href">https://medium.com/media/c8e57594a5464f10669ace359d7ec97b/href</a></iframe><p>Each of our scales will take in a value somewhere between the minimum and maximum of each variable in our data, and spit out a pixel value that we can use for our SVGs. I’m using the d3.min() and d3.max() functions here so that D3 will automatically automatically adjust if our dataset changes. I’m also giving our domains a 5% buffer both ways, so that all of our dots will fit on the screen.</p><p>We’re also reversing the range values for our y-scale, since an input of 0 should spit out an output of 500px (the bottom of a cartesian grid in the SVG coordinate system).</p><p>Next, we can make a few edits to our code from earlier, so that the values for our circles come from our scales.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/87f53c21537fc6fa9aaf8ac1c8460e7f/href">https://medium.com/media/87f53c21537fc6fa9aaf8ac1c8460e7f/href</a></iframe><p>At this point, we have something that looks like a real visualization!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4GO3p5mxapV3vz9mDzUaxg.png" /></figure><p>The next step is to add in some axes, so that we can tell what these dots are meant to represent. We can do this by using D3’s axis generator functions, but we’ll soon run into some problems…</p><h4><strong>Crucial Concept #4 — Margins and Axes</strong></h4><p>D3’s axis generators work by attaching an axis onto whichever element they’re called on. The problem is that, if we try attaching axes straight onto our SVG canvas, then we’ll end up with something like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Dij7WdNq0jjNXbooC-8o6Q.png" /></figure><p>Our first problem is that the axes are always positioned at the top-left hand corner of the grid. That’s fine for our y-axis in this case, but it’s not okay for our x-axis, which we want to place at the bottom.</p><p>Another issue here is that, since our axes are sticking out over the edge of our SVG canvas, our axis tick marks don’t show up for our y-axis.</p><p>We can fix this by making use of a few SVG groups — invisible elements for adding structure to our pages.</p><p>In D3, we need to get used to the “margin convention” that all of our projects should follow:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/786/1*1RmRQh986P-TlvLhnTd4NQ.png" /></figure><p>The idea is that we want to give ourselves a buffer around the edge of our visualization area, giving us some space for our axes to live. We need to set some width, height, and margin variables at the top of our file, allowing us to simulate this effect:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/f6f0169139b934ad3aac6abb8fd077f0/href">https://medium.com/media/f6f0169139b934ad3aac6abb8fd077f0/href</a></iframe><p>We now need to use these width and height variables to set the range for our scales, and we’ll be attaching our circles onto this g variable, which represents our main visualization area.</p><p>If we also attach our axes to SVG groups, then we can shift them into the right position using the transform attribute that comes with the group element. Here’s the code we’ll be using to add our axes onto our graph:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/9a3a05b864a50d5d5b14a7726601aac0/href">https://medium.com/media/9a3a05b864a50d5d5b14a7726601aac0/href</a></iframe><p>I’m also adding some text SVGs as labels, which will tell us what each of the axes is showing.</p><p>The margin convention can seem a little random for newcomers to D3, and there are a wide range of methods that we can use to edit how our tick marks should look.</p><p>Resources for understanding margins and axes in D3…</p><ul><li><a href="https://bl.ocks.org/mbostock/3019563">An walkthrough of our margin convention code — Mike Bostock</a></li><li><a href="http://www.tutorialsteacher.com/d3js/axes-in-d3">A guide to axis generators in D3 — TutorialsTeacher</a></li><li><a href="https://github.com/d3/d3-axis">The D3 API reference entry on axes</a></li></ul><p>Now that we can see what our chart is showing, I want to take it to the next level by adding in an update to our data. To do this, we’ll use the D3 interval method to run some code continuously:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/87d40233b6a2c66ce2ce7d5615eecdb8/href">https://medium.com/media/87d40233b6a2c66ce2ce7d5615eecdb8/href</a></iframe><p>Every 1000ms, this function is going to execute an update function, changing the data that we’re using between our two different arrays.</p><p>We need to make a few edits to our code to get everything to update like we want it to:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/f1754050515f8d476974acf9a12bf5a8/href">https://medium.com/media/f1754050515f8d476974acf9a12bf5a8/href</a></iframe><p>We’re setting our scale domains inside our update function, so that they adjust to the data that we’re working with. We’re then calling our axis generators here too, which will update them accordingly. We then have a confusing block of code, which handles how we want our circles to update.</p><h4><strong>Crucial Concept #5 — The General Update Pattern</strong></h4><p>The general update pattern is used in pretty much every visualization that you’ll want to build with D3. It defines the behavior of elements in our data that should enter, update, or exit the screen. As a beginner, all of this code can seem a little overwhelming.</p><p>Let’s take a closer look at what each of these lines are doing.</p><p>First, we’re binding our new array of data to our D3 selection:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/cdfd46560a5b8f310ec0ecb18b9879fa/href">https://medium.com/media/cdfd46560a5b8f310ec0ecb18b9879fa/href</a></iframe><p>Next, this block of code will remove all the dots that no longer exist in our new array of data:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/bc54502a7806c9d8cbd6018fee0b9704/href">https://medium.com/media/bc54502a7806c9d8cbd6018fee0b9704/href</a></iframe><p>Here, we’re updating the position of all the dots on the screen that still exist in our new data array.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/a40b123462fd9a00d17b06a164316b4f/href">https://medium.com/media/a40b123462fd9a00d17b06a164316b4f/href</a></iframe><p>Finally, we’re adding a dot for every item in our new data array that doesn’t have a corresponding circle on the screen.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/09970d638b11acc580be80ee8d66aa24/href">https://medium.com/media/09970d638b11acc580be80ee8d66aa24/href</a></iframe><p>The tricky thing about understanding the general update pattern is figuring out exactly what selectAll(), enter(), and exit() are doing. D3 works by using a set of “virtual selectors”, which we can use to keep track of which elements need to be updated.</p><p>Although you can get away with having only a surface understanding of the update pattern with many charts that you’d want to create, the whole library becomes a lot clearer once you can figure out what each of these selectors are doing.</p><p>Resources for understanding the general update pattern in D3…</p><ul><li><a href="http://quintonlouisaiken.com/d3-general-update-pattern/">A walkthrough of the general update pattern — Quinton Louis Aiken</a></li><li><a href="https://bl.ocks.org/cmgiven/32d4c53f19aea6e528faf10bfe4f3da9">An interactive exploration of the general update pattern — Chris Given</a></li></ul><p>Once we’ve added in our updates, here’s what our chart looks like:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/640/1*hxUTFWCTnqgXxwJ2HtnIbg.gif" /></figure><p>Our visualization is now flicking between the two arrays of data that we want to display. I’m going to add one more final flourish to make our graph look a little neater.</p><p>We can add in some beautiful transitions by making use of the superb D3 transition suite. First, we’re defining a transition variable at the top of our update function, which is spreading each of our transitions out over a duration of 750ms.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/716f5bd04bf2d77e9861ec632f1c659e/href">https://medium.com/media/716f5bd04bf2d77e9861ec632f1c659e/href</a></iframe><p>Any attributes that we set before calling the transition method on a D3 selection will be set straight away, and any attributes that we set after this transition method will be applied gradually.</p><p>We can add transitions to our axes like this:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/418138452893463dd6067d72d2f0401a/href">https://medium.com/media/418138452893463dd6067d72d2f0401a/href</a></iframe><p>And we can add transitions to our circles like this:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/b85f91ea4a90379a996f086276e1fb16/href">https://medium.com/media/b85f91ea4a90379a996f086276e1fb16/href</a></iframe><p>We’re transitioning between a fill-opacity of 0 and 1 to make our dots gently fade in and out of existence, and we’re smoothly shifting the updating circles to their new positions.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4jWVP5cKEbrKONacMmLWOA.gif" /></figure><p>So there we have it. We now have a beautiful scatter plot which is updating between different sources of data. You can find the finished product of all this code on my GitHub page <a href="https://github.com/adamjanes/scatter-demo">here</a>.</p><p>Although mastering the concepts in this article might seem like a huge step to take just to get started with D3, the code gets easier and easier to understand with practice.</p><p>You’ll soon find that the same key concepts underpin every D3 visualization, and that once you know how one visualization works in D3, you can quickly learn to build almost anything that you can imagine.</p><p>Check out the examples on <a href="http://bl.ocks.org/">bl.ocks.org</a> and <a href="http://blockbuilder.org/">blockbuilder.org</a> to see some ready-made implementations of so many interesting projects. Like D3 itself, all of this code is open source, meaning that you can copy any of this code onto your local machine, and use it for your own projects.</p><h4>An easy way to get started with D3…</h4><p>If you’re looking for the fastest and easiest way to learn D3, then I teach a <a href="https://www.udemy.com/masteringd3js/?couponCode=DISCOUNT-20">course on Udemy</a> which offers a comprehensive introduction to the library. The course includes:</p><ul><li>7 hours of quality video content.</li><li>A step-by-step introduction to the foundational concepts in D3, covering all of the topics covered in this article and more.</li><li>Four awesome class projects to practice the skills that you’re learning with real-world data.</li><li>A strong emphasis on data visualization design, helping you to create custom visualizations for your own data.</li><li>Walkthroughs of 12 of the most commonly used visualizations, teaching you how to understand and adapt pre-written community code for your own purposes.</li><li>An introduction to an object-orientated approach for creating complex web apps, where multiple visualizations on the page are updating at once.</li></ul><p>You can get the course at a discounted price of only $20.99 by signing up through this link <a href="https://www.udemy.com/masteringd3js/?couponCode=DISCOUNT-20">here</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8ca460f18787" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>