Write What You Know (Now)

Sometimes the writing comes easy enough, 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 episode 110 of The Web Ahead.

Article Continues Below

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:

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.

The fear of stating the obvious is one of my primary personal roadblocks to writing. Jeremy’s words evoke Samuel Pepys’ diary, which is a famously important resource for historians precisely because it includes so much detail about life in the 1600s—including many items that he could have dismissed as being mundane and obvious.

Non-experts please apply#section2

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 know this much, so far. Or even: Why is this happening? 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.

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 now, 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.

Lies your brain will tell you#section3

“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 interview with Ursula K. Le Guin, 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….”

On the other hand, that might be exactly what you fear—that someone actually will 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.

Getting more adept at writing can help you communicate confidently in other ways too. In a recent ALA On Air live event, Jeffrey Zeldman emphasized the benefit writing can have on your problem-solving process:

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?”

chmod 777#section4

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:

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.

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

Recently, CSS-Tricks ran a survey 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 blog post. Blog post! One of the other leading answers was “Q&A format page” (something like Stack Overflow). That made me think. Why wasn’t Q&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 why as much as how.

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: Technology’s Betrayal. 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.

23 Reader Comments

  1. Great article. We are trying to implement this at our web studio, but can’t find a natural tool or set of tools to write everything up, from quick thoughts, to links, to full-on posts or wikis. Would you have any recommandation for us? Thanks!

  2. I’ve never considered it from that perspective before but we can certainly learn a lot from what we think as we are learning. When we only write after we have learned something we forget all the mistakes we made and as a result do ourselves and future users a disservice because we cut off vital information.

    When we learn a command, sometimes the name might not make the most sense, but we often forget it’s original meeting because we now know it to do something different. The content we write when we are learning is just as valuable as the end result after we know something.

    There’s also a certain merit to writing about something that is already assumed to be known by everyone, and that is you may reach an audience in a different way due to your writing style, as mentioned in the post. If I remember that is how CSS Tricks got its start, Chris has a great way of breaking things down into an easy to understand manner.

  3. Guillaume, at Bluecadet we use a number of the things from my column that Rose linked to above. A lot of the devs capture their notes in nvALT, and we have a lot of shared Google Docs. But what I encourage people to do is write where they already have a presence. Whether they have their own blog or use Tumblr or Medium, keep writing there. A common thing I hear from web designers is: “I just need to redesign my site first.” I can tell those folks from personal experience that you will rarely (never?) finish that redesign to your personal satisfaction so don’t hold off writing.

  4. Luke, what sometimes happens to me is that I end up repeating the same mistakes I made, just because I never documented steps to get to a solution. I’ll be elbow-deep in code or configuration spaghetti and realize, “Wait. I’ve been here before”.

  5. Thanks Mark, I really enjoyed this article, especially your bit about almost bulk publishing your entire drafts queue. I write for living although I constantly feel as if I don’t get to write for myself nearly enough. I keep telling myself to just write something, even something is usually not utter nonsense and it fuels the habit. I don’t listen to myself as often as I’d like, though.

  6. Paul, I definitely hear you on that. I write almost daily in Day One—just snippets of daily life that I want to remember. Putting it there helps remove some of the pressure when writing on my blog. Later on (sometimes much later!) some of those snippets end up on my blog.

    The Ursula K. Le Guin interview I linked to above is really, really worth reading. She describes her work process but also doesn’t get prescriptive about it (especially where she talks about not having a writing schedule).

  7. When I’m learning something new, such as JQuery recently, I quite often do a quick search, find a code snippet, then copy and paste, modify it and try it out.

    That may fix it for now, but to understand what it is doing and why, it’s best to find a blog post and spend more time understanding what it is really doing so you know for next time.

    You could go to the official documentation site, but I often find the examples too generic, whereas a blog can be a real life example.

    So, thanks for this article, but also a big thank you to the community for helping me and all the other developers out with your writing!

  8. 1-855-826-7859 Q.u.i.c.k.b.o.o.k.s T>E>C>H s.u.p.p.o.r.t Phone Number, *+1-855-826-7859… 1 Answer Q.u.i.c.k.b.o.o.k.s (((((1855-826-7859)))) Q.u.i.c.k.b.o.o.k.s s.u.p.p.o.r.t number !!~@1 855-826-7859…
    Q.u.i.c.k.b.o.o.k.s telephone number for(((1/855/826/7859)))) s.u.p.p.o.r.t, Q.u.i.c.k.b.o.o.k.s HELP DESK NUMBER number!!+++!!1 855-826-7859)))))++@ Q.u.i.c.k.b.o.o.k.s .c.u.s.t.o.m.e.r s.e.r.v.i.c.e number !!1 855 826-7859 Q.u.i.c.k.b.o.o.k.s .s.u.p.p.o.r.t phone nu.mb.er , Q.u.i.c.k.b.o.o.k.s s.u.p.p.o.r.t phone number usa
    1+855+826+7859 q.u.i.c.k.b.o.o.k.s t.e.c.h s.u.p.p.o.r.t line
    1+855+826+7859 q.u.i.c.k.b.o.o.k.s online t.e.c.h s.u.p.p.o.r.t number
    1+855+826+7859 q.u.i.c.k.b.o.o.k.s t.e.c.h s.u.p.p.o.r.t phone number uk
    1+855+826+7859 q.u.i.c.k.b.o.o.k.s enterprise t.e.c.h s.u.p.p.o.r.t number
    1+855+826+7859 q.u.i.c.k.b.o.o.k.s proadvisor t.e.c.h s.u.p.p.o.r.t number
    1+855+826+7859 q.u.i.c.k.b.o.o.k.s t.e.c.h s.u.p.p.o.r.t phone number australia
    1+855+826+7859 q.u.i.c.k.b.o.o.k.s proadvisor t.e.c.h s.u.p.p.o.r.t number

  9. Wonderfully written, and just the kind of viewpoint I didn’t know I wanted to hear.

    I signed up just to comment this.

  10. Thank you for this. I’m a writer at heart, but I all too often let the hesitations you shared here keep me from doing what I love and I know is good for me. This was just what I needed to hear… Keep it up!

  11. Thank you!
    Stumbled upon this column randomly while seeking website typography inspiration, but found even greater one. Right on spot – I guess I’m finally gonna start my blog 😛

  12. I too just stumbled across this article. It reminded me that I need to start reading A List Apart regularly again.

    Inspiring stuff, thanks.

  13. I prefer blog posts to Q&A because the answers are so often just as obtuse as documentation. The thing I hate most is “go look at the specs.” “The specs” are often written for people creating tools or user agents and “The Specs” are written as if the only readers are engineers very familiar with the current topic.

    The best answers I’ve found are from blog posts where someone said, “I was trying to do something and it was hard. Here’s how I learned how to fix it.”

    I do thing Q&A is great, especially if you’re hopping between languages and you’ve forgotten the syntax of a particular kind of statement. Stack Overflow often rises higher in search results than jQuery docs or W3C specs. And with Q&A you get a variety of answers, often related to questions that have been asked of you, such as “What do you mean by X?” or “Maybe instead of what you are trying to do there is a better path, like X.”

  14. I’m currently writing my first novel and I realized they more I push to be witty the more I become manufactured. It is much better to just let it all out and go back in an aggressive edit and take it out. Write often means write better

  15. Thanks for this! As a relatively new coder (because 3 years in, I still feel like a total n00b,) blogging about my experiences and elaborating on the things I’m learning or that are stumping me has been intimidating to say the least. As programers we have a never ending sea of more seasoned peers against whom we can compare our knowledge, but like you pointed out, code has a story. Or rather, it has many stories! As many as there are coders out there…

  16. I really do agree with you, and thats why ‘im actually writing an e-diary, and i’m forcing myself to work on it at least every 2 days or so. We need to know what we used to think, its a fact!

  17. As editor web I salute the entire community, which I know gives trouble to get to this result.

  18. Twitter is an online social networking service that is in every nook and cranny; twitter login on your smartphone, computer, and tablet and can also be used to log in to other websites.

  19. Good written article. Especially the part about giving yourself a permission to publish. I feel doubts before publishing something. I’m trying to fight it with writing services but doubts are going away really slowly.

  20. Personal opinion is always work better. Just Write what you have on your mind. As a simple example could we the process of writing a Narrative Essay. You need to prove yourself, to explain your position in your essay. And only after that you will have a success.

Got something to say?

We have turned off comments, but you can see what folks had to say before we did so.

More from ALA