Making Your Writing Work Harder For You
training.kalzumeus.com
training.kalzumeus.com
By the way, if you're a regular-ol'-geek and wondering "I wonder if writing about technical topics could help me career-wise", the answer is "Absolutely yes." You can use blogging software but it probably isn't your benefit to adopt the blogging format of 500 ~ 1,000 word articles displayed in reverse chronological order about disconnected topics. Instead, you could make it a goal to write three pieces and polish them to a mirror shine.
(Related advice that I find myself saying frequently: If you publish OSS and expect to get anything via doing so, don't just drop the OSS on github. Spend the extra bit of time packing it into a site with a getting-started guide, a visual identity distinct from "Github rendering a Readme file", and the request that interested people $TAKE_THE_ACTION_YOU_WANT_THEM_TO_TAKE.
Here's an actual example, compare the READMEs for these open source RSS readers:
https://github.com/samuelclay/NewsBlur/blob/master/README.md
https://github.com/SSilence/selfoss/blob/master/README.md
https://github.com/swanson/stringer/blob/master/README.md
https://github.com/Athou/commafeed/blob/master/README.md
https://github.com/feedbin/feedbin/blob/master/README.md
https://github.com/gothfox/Tiny-Tiny-RSS/blob/master/README....
Which ones jump out at you? Which ones are memorable? Which do you want to install/contribute to/star?
(I'm biased because I wrote one, but I was very intentional which how the README looks and reads!)
To be honest, not yours. I'm immediately suspicious of "open source" projects written by OS X/iOS users and demonstrated on said platforms. Without installing your program myself, I can't expect it to work on GNU/Linux, since all of your screenshots are taken in Safari.
Anecdotally, I can say that I am going to have a look at the software, and this just because the author was willing to consider us Linux users.
I think that term matches up nicely with what you're saying.
This is so true. I think the bulk of my consulting work comes to me via my blog - I've put basically no effort into seeking it out. A conversation which happens with some regularity:
Bossish person: "We are having trouble with $MATHY_STUFF. Do we know anyone who can help us with it?"
Codeish person: "I've been following these tutorials on chrisstucchio.com..."
I'll disagree with patrick a bit about "a visual identity distinct..." and formatting, at least for people who never touch the frontend. The people looking for you probably don't care that much.
Here are some fugly blogs of people you'd almost certainly hire:
http://www.johndcook.com/blog/2008/08/21/random-inequalities... http://www.stephendiehl.com/posts.html http://elem.com/~btilly/ab-testing-multiple-looks/part1-rigo...
That said, dropping $1000 on some pretty visual design probably can't hurt.
In particular, some clients will eyeball your list of short tutorials, and see "A/B Testing", "HFT Algorithms", and "Ad Placement Optimization" and immediately form positive associations that they won't by paging through your old blog posts, which is something I just had to do to write this paragraph that very few casual readers will actually do.
You write something, you think it has lasting value, you should say so. It's a corollary of "ask for the sale".
You are misunderstanding one thing, however. People don't google "chris stucchio" and then find the tutorials - I think that's the use case you are discussing. They google "python monte carlo simulation" and find a tutorial in blog post format. They learn that I exist if they pay attention to the URL.
There's many assumptions we take for granted, even when we try to write evergreen. And sometimes those assumptions turn out to be overturned after a while.
When I happen upon articles, essays, blog posts, etc without a date, I usually trust it much less, and try to find similar information with a date.
The only way you'll know if your writing is evergreen, is over the course of time. I'll read stuff from 2002, and find it's still relevant, but we need to judge whether it is for ourselves every year. And not timestamping it robs us of that.
I suspect the best hybrid strategy, for those who feel dates complete a duty to the reader, is to put the date in small, low-contrast text near the bottom. Perhaps also, when minor edits occur, update one or more similarly-subtle 'updated' dates. That emphasizes the material is not obsolete/stale, but live reference material still maintained.
I do agree that the date doesn't need to be right alongside the byline but an indication of date somewhere on the page is important.
Edit: As for people who devalue something purely because of the date, are these readers you really care about? I suspect there are annoying readers just as there are annoying customers.
These sites also tend to have very obvious markers saying "this information is no longer maintained and only for historical reference" or "this information is no longer maintained but the new equivalent is here" where appropriate.
Personally, I find the indication that the information has been checked recently and is still current to be more important than when it happened to be published for the first time or when it was last changed.
http://paulgraham.com/identity.html
I think the cheap feel to blog posts partly comes from exact date (and time even) that's often shown on each blog posts.
At the very bottom, just before the backlink to the home page, I have (in a smaller font size) something like "Original publication on March 2nd, 2014, last changed on March 16th, 2014".
I don't have anything to hide, so it's there, but I don't see any real value in it for the reader. So I effectively buried it.
Decisions should be made to support the intended goal of whatever you are doing. A lot of creative work does not have a date stamp front and center and people still enjoy it.
For example, when a movie like Terminator 2 is played on TV, do you watch it? Sure. Do you freak out if you start in the middle of the movie because you don't get to see the opening credits? Are you annoyed that you don't have the date stamp on every frame so that you KNOW when the movie was produced?
We technical people might care a bit too much about formats and things, but to a normal, non-technical person i.e. most of your customers, they probably don't care. Most people don't check the copyright date on books or look up the year a movie was produced on IMDB.
Clearly, no one is suggesting any such thing. For movies, there's IMDB to find such things out. For blog posts, there is no IMDB, so if you remove the time stamp, you are removing access to a crucial piece of information.
It depends! Would you buy a collection of essays about how to best market on the internet from 1997? Maybe, maybe not.
Other stuff is pretty timeless (hey, this Shakespeare is old!), so it really does depend on what the material is about.
When I open a paper book or a blog post, the first thing I want to know is, "When was this published?" That immediately gives me context as to the state of the world when this was written.
This is a no-brainer when it comes to technical publications because technology is changing so rapidly but it's equally as true with any other type of publication (even fiction to some extend, but much less so than non-fiction; the same goes for movies: entertainment is not as time-sensitive as a documentary).
A date of publication provides context for the reader to know what world the author was living in when he/she was writing. That's very relevant.
On my personal site, I put the year of every post right in the permalink (e.g., example.com/2014/my-new-post/).
I only check a book's date when I'm trying to find out which edition I'm holding in my hands. It happens about once or twice times a year that I want to know that (admittedly more often in the last year since I was citing books in an academic setting).
Otherwise some imprecise idea about the publication date (Which decade? Possibly even less granular) might be interesting, but it's usually obvious from the layout, typesetting and so on.
I've really never wanted to know if a book was printed in 2008 or 2011, just to put the content into context.
I have. I'm quite interested in financial crash literature and the difference in context between a 2008 perspective (which may be interesting in its own way) and 2011 looking back at 2008 is pretty large.
Edit to add:
That isn't to say the article is wrong, I think well organised permanent content can probably live well without a date on it. There are definitely items of content for which a date is important but for others I can easily believe it would detract.
Movies, not so much, because they aren't seek current factual information in them. Books, when used as references on things that might change, yes, most non-technical people I know do consider how new a book is when evaluating them for that use, often checking copyright/publishing dates.
If an author fears the "bit rot" effect, then why not update the piece and provide an "updated" date, e.g.:
"Solving World Hunger with JQuery"
by Blister Peanuts, October, 2010
Updated May, 2014
But in Patio11's example on salary negotiation, the date isn't nearly as important. Some information is relatively timeless. I saw a comment on HN today advocating that people read "How to Win Friends and Influence People" and "The Prince". These books are still very popular today and were written in 1936 and 1532, respectively.
It really comes down to relevancy. If the date is relevant to readers, you should make sure it's easily found. If the date isn't relevant, why does it matter if it's posted anywhere?
And while everyone enjoys free articles, there's still a huge future ahead. When searching for technical problems it's not uncommon to get results from over a decade ago. The internet is still in its infancy, so please, let's take all possible care to not pollute it.
Note it only applies to technical subjects and other fast-changing areas. I wouldn't mind reading TFA if it was decades old.
Sorry for the confusion.
In that particular case, the book was about the business and finance side of independent film distribution. Information on that topic from 2007 is about as useful as an article on optimising web servers from 2004 - there might be some useful stuff in there, but a lot of it will be seriously outdated and the landscape's changed beyond recognition.
I also find articles on rapidly-changing technical areas to be essentially useless without time context. For example, I'll automatically discount any article about the more technical aspects of advertising on Facebook if it doesn't have a date on it. Advice that was valuable on that topic in 2010 is often useless or dangerous to your business in 2014.
Don't listen to them. Of course readers are smart enough to perceive long-term value in a blog post. But they don't, because appreciating that value requires them to expend mental energy to fight against the blog format. Instead, they see a blog post and:
* Assume that because it's on the blog it was written in a single draft.
* Assume that it's part of some larger conversation amongst lots of bloggers.
* Assume it's an invitation to a discussion among readers rather than your definitive take on an issue. (For extra fun: add a series of complaints about not having "comments" enabled on whatever you wrote.)
* Assume that it'll end up syndicated along with the rest of your blog posts on "Planet People Like You" or whatever blog aggregator you end up on.
* Assume that it'll be followed up on in some future post.
In general, the reader isn't wrong about this! Those beliefs are continuously validated by the majority of blogs. Which makes me wonder why anyone would sink days or weeks of effort into a piece only to deliberately position it alongside every other dashed-off blog post.
I think you can get immediate value just by doing what Patrick said: write a blog, but don't call it that. But you can do things that are much more creative, too. Our crypto challenges started out as a text file of 40 3-paragraph challenges. We thought about putting it up on the website, but we worried that we'd end up getting skimmed by people on (not to put too fine a point on it) HN who wouldn't really understand them, and end up "debating our own posts" with those people. So instead of publishing them, we accepted email addresses for people who wanted them, and doled them out 8 challenges at a time. More than 12,000 people signed up; we're finally releasing them in their entirety, along with solutions in every single mainstream language and a bunch of weird ones, in a Black Hat talk this year. It became one of our most profitable recruiting vehicles.
It was originally a blog post. Man, that would have sucked, if we stuck a date and a title on it and hit "publish".
When I'm looking up a topic it sucks to get halfway through an article and realize that half of the methods it recommends have been deprecated. If the author had bothered to put a date on the post I would have known to avoid it.
I think it depends entirely on the material and how long it's likely to be valid for. Basic principles of human nature, for instance, are likely to not change a bunch from one day to the next (although research might reveal new views on them). How to install mod_perl on Apache in order to create actual dynamic web sites... Perhaps that's best left to the late 90ies.
OK, but then why not then update the date of the article?
Every so often I find myself reading something and start to wonder if it's still current. It's frustrating to not then find that date the article was written or last updated.
Basically, I don't see a downside for including a date, but there are assorted pitfalls for the reader if omitted.
For something where specific versions or dates matter, nothing about the article suggests that you not address it in the "post." If a configuration file changed in April, 2013 then you should write about how it changed and how to deal with the different versions. And if you're writing about something specific to Python 3, you should be specific about that restriction. But I don't see how dating the article as "August 17th, 2013" is going to effectively communicate either of those nuances.
The article date is at best an imperfect proxy for whether the information is current. And the OP and parent are claiming that prominently displaying the date (and other "blogging artifacts") cause potential readers to discount the information more than they should. I don't know whether the argument is universally true, but it's plausible.
Whereas if you right one with no date, I'll just distrust it and look for one with a verifiable date. If I know how outdated it might be, that gives me some confidence -- I can look at it and use other sources to determine if there are relevant changes to the related platform that need to be taken into account.
If I don't, I can't. In general, my assessment of technical information online is Current > Old > Uncertain.
One way to put it is: if I put a date on my writing, I accept a finite but certain discount on its value. If I don't, I risk an unbounded but uncertain discount, depending on how valuable the content itself proves to be.
If I'm writing a piece on how to do TDD with rspec, that unbounded discount is nearly certain to occur, because the subject itself is fixed in time. But I'm writing a piece on using advanced statistics to optimize ad placement, or on why people shouldn't use narrow-block deterministic disk encryption algorithms to encrypt individual files, the subject isn't anchored to any particular time, and the discount I take for adding "uncertainty" by losing the dateline is unlikely to materialize. Whereas no matter what I do, if I write that ad placement post as a blog post, it's dinged as a blog post.
And I know you're wrong, as to me (can't speak for "many others".)
> One way to put it is: if I put a date on my writing, I accept a finite but certain discount on its value. If I don't, I risk an unbounded but uncertain discount, depending on how valuable the content itself proves to be.
Both are uncertain, really.
> If I'm writing a piece on how to do TDD with rspec, that unbounded discount is nearly certain to occur, because the subject itself is fixed in time. But I'm writing a piece on using advanced statistics to optimize ad placement, or on why people shouldn't use narrow-block deterministic disk encryption algorithms to encrypt individual files, the subject isn't anchored to any particular time, and the discount I take for adding "uncertainty" by losing the dateline is unlikely to materialize.
Especially in the former case, its not entirely obvious that the subject matter is inherently not fixed in time (while the statistics may not be, the application seems to be very time sensitive. A reader can, of course, evaluate whether there are relevant changes, but not without information about the context -- and particularly the time -- for which the piece was written.)
> Whereas no matter what I do, if I write that ad placement post as a blog post, it's dinged as a blog post.
Aside from "official" sources (projects own documentation sites, etc.) pretty much the most useful sources I find on technical subjects are blog posts.
OTOH, there's certainly probably many cases where utility for the poster of advertisement-disguised-as-technical-information differs signficantly from the utility to the reader of actual technical information. And I don't doubt that often, at least in terms of drawing certain types of business, concealing the date of information is useful for doing that -- there's a reason why ads, even when posted in places where they will be exposed for a very long time, rarely have dates on information, and when they need to, its often in microscopic print in disclaimers.
Similarly, a downloadable e-book does not transmogrify from "useful technical information" to "disguised advertisement" simply by living in an undated PDF document behind a paywall.
Well, if its a behind a paywall, its probably not a very good advertisement. But I was discussing, at any rate, the difference between factors impacting the utility of a particular piece of writing as useful technical information for the reader vs. those affecting its utility as a advertising for the creator/publisher -- those two roles can coexist in the same piece of writing at the same time (they don't require anything to "transmogrify" from one thing to another to change between them), they are utilities related to different interests that different parties have with regard to the material, not to inherent differences in what the material is.
Concealing the date can simultaneously make the piece of writing more useful to you as an ad, while making it less useful to the reader as technical information.
Meanwhile, you continue to refer to technical writing that lacks a dateline as an "ad", which is self-evidently false; technical writing does not become an advertisement merely by dint of lacking a dateline.
Edit: added "(necessarily)"
Well, specifically, its that "readers interest in gathering technical information is distinct and often at odds with the promotional purpose that publishing information serves for authors/publishers" -- there are other (also potentially conflicting, in some cases) interests each might have, but I was specifically focussing on one interest of readers and one interest of authors/publishers.
> Meanwhile, you continue to refer to technical writing that lacks a dateline as an "ad"
No, I don't. I refer to advertising for the author as a role which technical writing may have for which omitting the date may be useful even when it is counterproductive to the utility of the piece in its role as a source of technical information for the reader.
> technical writing does not become an advertisement merely by dint of lacking a dateline.
Nor have I, even once, said that it did. So I'm not sure why you feel the need to keep denying this claim that was never advanced.
Well, sure, it would be "best" in terms of maximizing the initially perceived value of the information you are providing by negating inputs to the reader's initial assessment when they would work against you.
Of course, if the reason people's filters work that way is experience-based rather than some innate feature of psychology, the utility of that practice will wane over time and as experience alters the assessment.
> Would it be dishonest to tell you that today's post was written today, but not say when a post from three years ago was written?
To an extent, yes, it would be dishonest, especially if the whole point is to withhold information about currency only when it would weigh against the reader's assessment of value. Practices of that type (highlighting the newness of new content but avoiding discussing the datedness of other content) are pretty common, though.
E.g., writing about recommendations for Python programming, and stating that you were running Python 2.7.5 at the time, or whatever.
that is the killer - articles and books carry their own context. Even well written articles that start with "As Fred smith commented on his well received blog" have a huge mental drag of having to go read Fred's article, grok that context and then come back and ...
Self contained, even though having good references is still best.
There's sometimes a happy medium - you can deemphasize the date with CSS or by putting it at the bottom of the post.
Here's an example of a blog-style post on my site: http://joshkaufman.net/malinvestment/
People who want to find the date can find the date. People who aren't looking for it aren't likely to see it.
Such as if you wrote a post in May 2012, then in May 2014 adding a quick intro saying "Updated May 2014: I've added x, xy, and xyz, but this post is still relevant today." or something of the like?
Supplying date meta is as basic as having contrast between your font and background and having font set at a legible size. "Because you don't owe it to a reader" does not really make for sound reasoning if you ask me.
The nomenclature of content is mostly irrelevant to this. It doesn't matter what you call it, an essay, article or tutorial. Still benefits from date meta.
Case in point: any luck finding tutorials for say, a recent version of backbone.js? You have to look hard as most of are out of date and even if they are up to date, it's hard to tell (knowing when a piece of content has been updated is just as important).
Hiding the date meta just makes it all the harder and it's reader-hostile. If you are writing about a topic, it's to benefit a person looking into a topic. I think some people are missing the point of creating the content in the first place.
If you want your content to appear valuable vs less valuable, write the hell out of your content. Make it impossible to discount the content by making it stand out.
In science, researchers don't cherry pick and refer studies written in the last 5 years. They go back as far is relevant. They will refer back to hallmark papers regardless how old. Same with nonfiction books. Same with well written blog posts, because good blog authors often cite references to give the proper context. That's kind of the point of blogging, the power of linking and building upon what has already written. But making a piece of content float in some unspecified time vortex disrupts that.
What's more is that a clear date indicates that the author wrote it at a certain time. It makes it harder to distinguish people that copy content or write about similar copycat ideas from their more original authors.
For what it's worth, I'm not against the idea of situating your content in the best way possible. I think using categorization like tutorials/articles/essays is a better way of framing certain types of content. That can help the reader. Hiding the date meta is an attempt to help the author, while hampering the reader. It doesn't even add up.
Point still stands though, are PG's essays devalued because he puts a year date on them? I don't think so.
I would hope that backbone.js releases carry version numbers. As a developer I usually know the versions of the tools I'm working with. But I might not know (and often don't) when exactly they were released.
I happen to agree with the people who are annoyed by the lack of a date. For most technical topics I research, I want to know when the article was written. Even for nontechnical topics, I generally want to know if the article represents the author's current thinking or something more distant.
But I'm not most readers, and like tptacek pointed out I'm certainly not entitled to a date on the post. Since I am unlikely to hire the writer, optimizing for my happiness is not exactly expected here. Of course, if I were to be looking to hire the reader, stale content isn't really going to bother me. It could of course affect if I see the content at all (via a search), which I expect may be one of the larger points here.
I'm a huge fan of Patrick's, but I couldn't disagree more on this point.
Choosing to write primarily about evergreen topics is ONE valid approach to creating value, but it's not the only one.
It's equally useful to write about topics that people have a burning desire to know more about, even if that desire will fade over time, provided you are building that knowledge into your strategy.
For example, one of the sites I run provides accurate, up-to-date information on optimal builds for World of Warcraft characters. That's the very definition of information that becomes rapidly useless. However, the time it takes to write those guides compared to the value it provides to me (in terms of advertising revenue) and my readers (in terms of giving a quick, accessible answer to a question they really want authoritative information on) makes those guides a very solid business proposition.
Likewise, I started an information site about the Oculus Rift a while ago. Again, everything on there is going to go out of date relatively fast - but whilst it's relevant, it's extremely relevant. And that allows me to build the site on a very small time investment and be in a good place to ride the wave of the DK2 and consumer release.
This is HN, for goodness' sake. Half the things we're likely all interested in are ephemeral. Anyone ever searched for information on Ruby on Rails configuration? Or Heartbleed? Neither of these topics are unlikely to change over time (said he, looking sadly at the wreckage of his Rails 1.0 sites), but it's still a solid decision both for business and value-creation reasons to write about them.
However, choosing to focus on evergreen topics is also a valid strategy.
(The rest of the article, by the by, is fantastic advice, and by the end of the week my main site is likely to be split into "news" and "articles", the latter of which will have a significantly deprecated - but still visible - date field.)
1. If you're intention is to write evergreen content, you should probably separate it from your blog so people don't automatically assume it's less valuable. Like it or not, the date and format matter. At the very least, I would create a separate page to highlight the more important articles.
2. I would make sure to include a date on some topics, like tech that's going to change rapidly. Not every topic needs a date though, like his salary negotiation article.
You said some of this too, but just felt like summarizing myself.
- Don't call your writing "blog". Call it essay, guide or article.
- Don't put a date on your writing.
- Show your best writing up front.
- Collect email addresses, send your writing by email, track conversations.
- Keep detailed notes about your previous experiences and re-use them.
- Don't just write for other experts. Write for beginners.
Only blogging is like handing someone a stack of leaflets with some semi-descriptive tags on the side to help you navigate through them. A good test is to ask yourself if this would be useful or compelling if someone handed you a print version of the text.
Blogs developed the way that they did, I think, because they really took off as a way to socialize about the news, usually created for print or TV first. Social networks have taken over that role. Now, web publishing is beginning to take a more leading role rather than being wagged by traditional media. It helps to hold your writing to the same standards of quality that you would in a print publication.
For example "A guide to better salary negotiations, 2014 edition", etc. with some minor updates to reference new examples, anecdotes, popular businesses of the day, etc.
I think this could have the dual effect of reengaging previous readers with content they've already read as well as keeping your content fresh and giving you the upside of having a brand new article to (re)publish. In my own experience, I don't mind and actually enjoy rereading articles I've read before and enjoyed so I don't think as a reader, this would bother me at all.
I get the feeling that Medium.com is trying to build a platform for this too. The date is still there, but it's deemphasized and placed at the bottom, instead of in the byline. Someone could easily append "2014 edition" to the title - or perhaps, Medium could offer that feature too.
Current Survey Results: http://moz.com/search-ranking-factors
Past Survey Results: http://moz.com/search-ranking-factors/2011 http://moz.com/search-ranking-factors/2009
"System Builder Marathon Q4 2013", "System Builder Marathon, Q1 2014"
Also if you pull the authorship code from the template, make sure you don't leave any class="hentry" unless you like seeing a crap load of structured data error messages in WMT about missing author details. I don't remember seeing any mention of reserved class names in the HTML spec so it would be nice if the Googlebot was a little smarter about that.
Both of those are just spamming techniques.
If it doesn't have a date it's almost certainly worthless content. Having a prominent date is actually a huge positive credibility sign.
The truth is just have an audience/subject in mind and cater towards that. Writing a technical article that depends on current state of technology? Put a timestamp on it. Writing evergreen advice about salary negotiation? No need to put a timestamp on it.
It's also quite a stretch to point to any of Patrick's writing (or, I guess, mine) and call it "spam", or its promotion a "spamming technique". You probably didn't mean to say that, but that's the impression you created, by giving undue weight to spamming tactics. And your penultimate sentence is, of course, trivially refuted.
1. Get a laser printer
Sorry, Amazon, but the truth is that staring at the flickering, dancing lightbulb that you call a computer screen wears the eyes, and can lead to serious sleep disorders. e-ink readers are okay but, for an essay of this magnitude, there's still nothing that beats good old fashioned ink-on-bleached-woodpulp.
And don't even think about using ink-jet. For the price of the ink, you could hire Patrick for a full one week consultation.
2. Paste the text into a wordprocessor
If you're au fait with LaTeX you don't need my help here. But for the rest of us, a word processor is the way to go. And, for you Windows users, bypass WordPad and go straight to MS Word (if you have it) or LibreOffice Pages (if you don't). Either is fine.
(In the past, I would would have suggested WordPad in a pinch, but LibreOffice is free and has important features that we're going to make use of.)
Now, at this point, you'll encounter a technical snag. If you just blindly copy and paste the text into your word processor, the formatting will come out all messed up. This is because Patrick uses '90s style tables for website layout. This is no big deal -- just go to the webpage, open up the developers' console, and copy-paste the text one table-cell at a time -- but you need to be aware of it.
3. Find and tag the section headers
There are usually 4- or 5- section headers in the text. Pick them out, and tag them as section headers.
4. Style your text
If you're a design maven, go knock yourself out here. The system I've found that works for me is:
- typeface: Arial Condensed 6 point (hate it all you want, but it's free and it gets the job done)
- page layout: minimal margins, 3 column
- paragraph style: 1 cm indent, no leading or trailing space, full justification
For the section headers, I allow myself a generous 9 points bold font size.
5. Check your printer
Make sure you have plenty of printer ink and paper available, because this is going to be a big job. And make sure you're not going to need the printer for anything else for a while.
6. Print!
By the way, don't attempt to take a Patrick McKenzie essay with you on a plane: you'll exceed your in-flight handluggage allowance.