title: Write What You Know (Now)
url: http://alistapart.com/column/write-what-you-know-now
hash_url: bab01f4f3937bf301e8ac32b0ca01810

<p>Sometimes the writing comes easily, and then there’s the last two months. I really wondered if I had run out of things to say. I knew I wanted to write about how more web designers and developers need to write about their work. So I wrote a bunch of paragraphs down, and then on a lark (I’m not even a regular listener), I downloaded <a href="http://www.thewebahead.net/110">episode 110 of The Web Ahead</a>. </p>

<p>I nodded along with host Jen Simmons and guest Jeremy Keith saying some very smart things about the web and its roots as the El train cut across Philadelphia. But at the 48-minute mark things got weird, because Jen and Jeremy basically started writing my column for me while I listened. Jeremy said:</p>

<figure class="quote"><blockquote><p>I wish people would write more… In the future, we would have a better understanding of what people are thinking now. I’m very glad that I’ve been doing my blog for 15 years. I can go back to 2002 and get a feel for what it was like to build websites. Back then we thought X was true or hadn’t even considered Y. You forget these things. Having these written records—not of anything important or groundbreaking—but just the day-to-day. The boring stuff. That’s actually what’s most interesting over time.</p>
</blockquote>
</figure>

<p>The fear of stating the obvious is one of my primary personal roadblocks to writing. Jeremy’s words evoke <a href="http://www.pepys.info/faq.html">Samuel Pepys’ diary</a>, which is a famously important resource for historians precisely <em>because</em> it includes so much detail about life in the 1600s—including many items that he could have dismissed as being mundane and obvious.</p>

<h2>Non-experts please apply</h2>

<p>I appreciate a well-written, logically-structured, authoritative blog post about code as much as the next person. But I also have a love for the blog post that is written with a posture of humility: <i>I know this much, so far.</i> Or even: <i>Why is this happening?</i> Seeing your own stop-start journey through design and code reflected in someone else’s writing can remind you that it’s ok to not have everything figured out. Turns out nobody does.</p>

<p>Often when a teammate shows me something cool, at the end of our conversation I’ll half-jokingly say, “write it up.” I think that’s pretty good advice regardless of where you currently sit on the continuum of despair to triumph. Don’t even wait until you have everything figured out, at the end of the project. It’s ok to write what you know <em>now</em>, while everything is fresh in your mind and the sheer agony (or thrill of discovery) borders on the physical. If you’ve just solved a particularly flabbergasting problem, imagine yourself on the other side of that experience, just hoping that DuckDuckGo or Google will turn up a post with even the barest hint of a solution. If that were you, you wouldn’t care that the blog post wasn’t polished. You’d just thank your lucky stars that someone took the time to bang something out and hit publish.</p>

<h2>Lies your brain will tell you</h2>

<p>“But nobody will read it,” you say. That may be true. But the opposite could also happen. A few years ago I was interviewing for a job, and my future boss said, “I like how you articulate things. I’ve read some of the stuff on your blog.” I was so surprised, I didn’t even think to ask which posts she liked. For all I know it was the ones where I recount the silly things my kids say. That memory made me think of this fantastic <a href="http://www.interviewmagazine.com/culture/ursula-k-le-guin">interview with Ursula K. Le Guin</a>, where she says, “There’s always room for another story… So if you have stories to tell and can tell them competently, then somebody will want to hear it….”</p>

<p>On the other hand, that might be exactly what you fear—that someone actually <em>will</em> read it. But that needn’t be an intimidating thought. Through your writing people can to get to know you, in a way that often gets lost in casual interactions with coworkers (or formal ones with a potential boss or client). Because if you read enough of a person’s writing, their voice comes through. It doesn’t matter if it’s just explaining a technical issue and offering a solution. Their quirks, their interests—these things bleed through if you read enough of their words.</p>

<p>Getting more adept at writing can help you communicate confidently in other ways too. In a recent <a href="http://alistapart.com/event/drweb">ALA On Air live event</a>, Jeffrey Zeldman emphasized the benefit writing can have on your problem-solving process:</p>

<figure class="quote">
<blockquote><p>I think if you can articulate your thoughts in writing, even though that’s really hard, you’re going to be better in meetings, you’re going to have a point of view; you’re not going to roll over and say, “The client said I should make the button blue and make it bigger, so that’s what I will do,” but instead will go, “What is behind the client’s request? What are we really trying to achieve?”</p>
</blockquote>
</figure>

<h2>chmod 777</h2>

<p>So now that you’re convinced, where do you start? You might start by giving yourself permission: “I allow myself to publish this thing.” This is one of those things that I’m still working on, myself. I’ve always found writing enjoyable, even easy. Publishing, however, is not. I’ve been blogging for several years, but my ratio of drafts to final posts is pretty dismal. This column has been good for me, because now I’m accountable to someone other than myself. I’ve got an editor that I don’t want to let down. I’ve got folks who actually read this column and respond. But maybe you don’t need more accountability. Maybe you actually need to lower the stakes, and give yourself permission to just get it out there. And again, Jeremy Keith said something along the lines of what I wanted to write:</p>

<figure class="quote">
<blockquote><p>The whole point of the web is there isn’t a gatekeeper. There isn’t someone with a red pen saying, “That isn’t good enough to be published. That’s not up to scratch. You’re not allowed to publish it.”… It could be the worst thing ever and you still have the right to publish it on your website. You should do it. Don’t let anyone tell you otherwise.</p>
</blockquote>
</figure>

<p>Holy smokes. I heard that, and I almost bulk-published my entire WordPress drafts bin.</p>

<p>Recently, CSS-Tricks <a href="https://css-tricks.com/dear-css-tricks-reader-who-are-you/">ran a survey</a> that asked its community to weigh in on topics that they face daily. I answered the survey, and one of the interesting results was for the question, “You’re stuck. You search the web. You prefer to find answers in these formats:”. The top answer was <em>blog post</em>. Blog post! One of the other leading answers was “Q&amp;A format page” (something like Stack Overflow). That made me think. Why wasn’t Q&amp;A the top answer? Maybe it’s because while web designers want something that works if we simply copy-and-paste, we are also driven by <em>why</em> as much as <em>how</em>.</p>

<p>Code has a story. One of my favorite posts to write (and read) goes something like: “This wasn’t documented anywhere I could find, and it’s such a weird situation that if I don’t write about it nobody would believe me.” I made a category on my blog just for those posts: <i><a href="http://dirtystylus.com/category/technologys-betrayal/">Technology’s Betrayal</a></i>. I feel like a web designer’s life is full of those little stories, every day. And usually you tell your teammates over lunch, or over a beer, and you laugh and say, “Isn’t that nuts?” Well, I’m here to say, “write it up.” Let someone else hear that story, too.</p>
