ri/blog

I’m hoping this will be my last Hyde-based post - I’m really excited by the idea of moving to Hugo, and I’m tired of Hyde’s issues (really, Python’s issues that Hyde does not sufficiently insulate the end user from). We’ll see - moving a blog from one platform to another is not an endeavor to be taken on lightly, but that doesn’t preclude it from being fun, if you can allocate the time for it!

While at Libreplanet (which was awesome, guys, omg), it struck me that there’s a disconnect between the needs of project maintainers, and the needs and tendencies of new users, who are inclined to provide an oppressive barrage of basic questions. Imagine if you were trying to use the same servers to build-bot LibreOffice, and host Wikipedia. Two heavy, unending services, warring for limited resources. Even worse, we are not machines, we are people - the “build-bots” are often the only people who are knowledgeable and capable enough to do that job, and that’s the job they want to do. It’s just that they’re also, unfortunately, the only people who know enough to document or mentor.

Oh, add one more bonus on top of this - if you treat the noobs badly, you are an unfriendly community. They may be collectively an oppressive force against development speed and sanity, a heavy drain on the willpower and motivation of the developers. But they’re also individuals, and if you treat someone with hostility, you not only fuck up that person’s day, but their impression of your product, and of the free software community as a whole.

XKCD 979: Wisdom of the Ancients
XKCD 979: Wisdom of the Ancients

Obviously the HTTP-esque server model is not scaling for us, and while RTFM (Read The Fucking Manual) is a mitigating strategy, it can have disastrous results if not tuned properly (use it too sparingly, and it might as well not exist at all - tell everyone to “google it, moron”, and see how fast your reputation goes from hero to tyrant). What we really want is a strategy that scales like BitTorrent, where supply and demand go hand in proportional hand, reducing the educational load on developers as the popularity of the software increases.

My proposed solution is an inversion of RTFM, called Write the Fucking Manual.

The Trade

The key to WTFM is to turn every seeker of knowledge into a provider of knowledge. This is more easy than it sounds! It is simply a matter of respecting that developer time is valuable, and should not be begged, but traded in kind:

When someone wants help, they must offer, in return, to document the solution to their problem.

This has quite a few benefits:

  • Builds and improves global documentation.
  • Imposes proof of work on questions.
  • Emphasizes value of questions that are most poorly documented.
  • Encourages users to check for existing answers, but empowers them to write their own, when the existing stuff is murky.
  • Explaining something is often the best way to learn it.
  • Fosters tutoring and collaboration
  • Gateway to greater involvement
  • Mindshare and reputation

I intend to go into more detail on every single one of these, as the summary only scratches the tip of the iceberg with our hull of realization.

Builds and improves global documentation

First of all, this approach scales knowledge production with knowledge demand. Already a big win!

But where this really shines, is projects that don’t have much popularity or documentation at all yet. The little guys. Big projects tend to eventually accrete a self-sustaining userbase either way - look how many questions about NodeJS are solved on StackOverflow, and you better believe those guys aren’t even unconsciously apply the WTFM approach. Once you get to a certain size, you don’t have to - the community kicks in, and you get those userbase-documenting benefits naturally.

So why go with WTFM at all, if you’re just going to get some amount of community documentation anyways? …Because especially when your project is small or poorly documented, you need all the help you can get. Because even as a large project, you can grow a healthier and more immense ecosystem of knowledge by committing to write down all the things. And because when it comes to documented solutions, enough is never enough.

You might argue with that last assertion. “If there’s too much stuff on the internet, how will people find what they need?” But this is a very old-world way of thinking. The internet never gets full, it only gets bigger. Search engines sort the relevant from the less-so. More written work means that the exact, specific solution to your problem is more likely to be on page one of your search results. It always makes the answer easier to find, not less. So yeah, let’s make the internet big.

Proof of work

Let’s say you were having a problem with people knocking on your door, at all hours of the day, to ask you things. If you made a rule that nobody could do that, without first spending 10 minutes dancing the Tarantella, nobody would bother you with stupid questions, would they? No, it would only be worth the trouble for questions that aren’t a basic Google search away.

Adding a “proof of work” to the question-asking process helps filter out dumb, FAQ questions. And because it’s not a useless or arbitrary requirement - it has a positive and immediate practical payoff - it doesn’t really filter out good questions. In the end, you not only rate-limit how many questions the primary devs have to answer, you also filter it to just the good stuff.

The worth of an offer

There is a rate-limiting factor on redundant documentation, as well. Every core developer-sourced solution is a trade, dev time vs. documentation, and it is up to the developer to decide when that trade is a worthwhile one, and when it’s not.

For basic questions, this is fairly RTFM-like. “Yes, you’re willing to document this solution for us - but that’s already handled by many other pages, so additional documentation isn’t a big enough reward.” So well-answered questions have an additional layer of filtering, beyond just proof of work, that helps teach people to always look stuff up before asking.

For advanced questions, askers are incentivized to make their questions clear and simple, to break down the problem into a simple demo of the failing behavior. This is because askers are bidding for access to a scarce resource - developer time - and we’re explicitly treating that time as a scarce resource.

WTFM teaches askers to be salespeople and researchers, and to understand the value of both developer time, and their own contributions to the ecosystem.

“WTF does that mean? I can do better than that.”

Sometimes a system or problem is documented, but really poorly. Vague wording, abundant jargon, large pages that are hard to grep for the parts relevant to your current situation - all of these and more can be symptoms of poor documentation. An RTFM approach can dismiss this problem by assuming that the existing docs are good enough, when in practice, learners can say from experience that these resources are insufficient (or inefficient).

In a WTFM community, the asker is always proposing, “help me make this better,” instead of just “help me.” This may mean creating documentation where none exists, but it can also mean writing superior documentation to what already exists. And it’s easier to convince the developers to contribute (vs RTFM), because the cost to the developers is minimal - filling in the blanks of existing manuals, explaining jargon, etc. A developer is much more likely to say yes to “let me write a better manual” than “I demand that you fix your manual on your own time”, since the cost of the former is low, and the reward for both parties (and the larger community) is great.

In addition, learners are often in a better position to write documentation, because they have a learner’s perspective. Developers often write manuals that they think are perfectly good references, but are useless to anyone who isn’t already deeply familiar with the workings and mindset of the code. People tend to write for an audience like themselves, so the best people to write documentation for learners, are often other learners.

Learning by teaching

One of the best aspects of WTFM, I’ve barely even hinted at so far. But it’s a well-known phenomenon that teaching a subject helps you to learn it better yourself. Explaining how stuff works, forces you to think about it from new angles and a greater depth than simply making your own code work - in fact, this is the entire basis of rubber duck debugging!

Giving someone the answer is one thing. Requiring that they restate the answer and put it in some form of public record, is quite another. In many situations, the former can produce no learning at all. You’ve simply fixed someone’s immediate problem, without them understanding the fix, or why it worked, or why the old approach did not. By adding a requirement of teaching, you are really requiring them to understand, while giving them one of the best possible tools to accomplish that understanding.

Helping you help me help you help us all.

Askers are never alone in the task of documenting solutions. The askee is right there with them, providing guidance and (often) a proofreading capacity for technical accuracy. The trade goes both ways - the asker pledges to document the solution, the askee pledges to help them do it. The result is a collaborative effort.

This can work especially great on wikis, where the changes can be edited by either party, misconceptions can be quickly corrected in both text and understanding, etc. It can also be a great use of Etherpad as a collaborative draft writing tool, which can be particularly handy if the end result is to be posted on a blog, which is not a collaboratively editable environment (but even wiki-bound changes can benefit from the instant feedback and chat channel).

Especially on advanced problems or complicated problem domains, there may be significant assistance involved. However, the benefit to the developer is clear - every piece of published documentation, is that much less information they have to manually explain again later.

Gooble gobble, one of us!

There is another huge mutual benefit to WTFM. After people get over the cognitive hill of their first contribution to your project, they will be significantly more likely to contribute to your project again in the future! And for that matter, to open source in general.

It’s well known that documentation work is often a “gateway drug” to becoming a more serious contributor. There are many people who started out fixing spelling and grammar in a project, and over time became mid-level or core developers. WTFM helps to push people through the “hardest” part of that process, proving that it wasn’t so hard after all, contributing is fun!

It’s all about feeling an ownership stake in a project. Even after the smallest contribution, you feel invested in the success of that project, at least a little bit. And that’s awesome! That’s the warm fuzzy glue that holds our open source world together.

For that matter, if your project is hard to contribute to, you’ll know about it. It won’t be this silent thing, where you don’t really know why nobody else is working on your stuff, and you never really optimize for it to happen. If it’s hard to contribute, that will become a pain point that demands an immediate fix. This can open you up to a whole new world of contributors, who you never knew you were losing with your pain-in-the-butt contribution process.

This is why WTFM isn’t just a way to automatically, artificially grow your documentation. It’s a way to push your project into a state of organic growth!

“Foobar, eh? I’ve heard a lot about that…”

There’s no visible difference between lots of people using your code silently, and nobody using it at all. If you have a relatively unknown project, statistically, it will probably stay that way for quite awhile. You are caught in a Catch 22 loop:

  • Nobody using your code
  • Nobody talking about your code
  • Nobody knowing about your code
  • Repeat, because even when people do use your code, the world never sees it

The best way to break out of this loop is for your users to be visible. If you can get them talking about how to get stuff done, get stuff fixed, get cool new features out of your stuff, then that’s the kind of thing that shows up if someone googles your project. It is immediately apparent that there’s a community out there; if you run into problems they will be solvable, you are not alone when you compile Foobar.

By getting the most “community-ness” out of your community, you can rapidly increase public awareness and reputation - maybe a bit faster than your still-immature code is worth! But communities are also great for pushing the edge cases of software, finding and fixing bugs (especially if you’re accumulating contributors). So put your anti-production warning labels up, but otherwise, don’t fear the spotlight. It could end up being your biggest asset in improving the quality of your code.

WTFM for free!

One of the great things about WTFM is that if you’re already using a public, archived medium for asking and answering questions (StackOverflow, an issue tracker, etc.), you’re most of the way to WTFM, since you’re automatically recording knowledge as people ask!

In this case, the only missing piece is to require that the asker restates the solution in their own words, to get the “learning by teaching” advantages, and to record the answer from a learner’s perspective. This may be omitted in situations where the overhead would have no benefit.

These “for free” advantages only count if it is easy to find recorded solutions via normal search engines. If they are only indexed by your own in-site search, that’s not good enough. If you don’t even have that (and no external search engines can index), you fail at this completely. Information that cannot be found might as well not exist.

Ways not to do WTFM

It’s not all silver bullets and cat pictures. Like any social algorithm, there are ways to implement it wrong, wrong, wrong.

Demand that the asker does all the work

WTFM is about a collaboration. The asker should do as much of the work as he/she can shoulder, but the answerer is a tutor, proofreader, and general fountain of knowledge. If the asker could do everything alone, they wouldn’t be asking.

If you (as a developer) aren’t contributing to the solution, then you’re not really using WTFM (at least, as it was intended), you’re just wielding a greedier version of RTFM.

Deliberately introduce issues so that people will document them

I can see some people trying to “hack” WTFM’s community advantages, by breaking some windows and giving people jobs to do. But really, you don’t need to do this. Your code has bugs already, I promise you. All software does.

Document my nothing!

You should have an easy-to-build project that does things before asking people to try it/contribute. If there’s nothing but a README, you’re doing it wrong. If your project is painful to build on other systems, that’s a problem that needs to be fixed.

It’s totally understandable to be psyched about WTFM, or your own project, and want to try this approach out before there’s anything to document. But don’t. It doesn’t make sense, and could give your project a reputation of being vaporware.

Saying no to everything

If you refuse to help anyone, you’re just depriving yourself of documentation and contributors (not to mention goodwill). If you say “yes” to helping an asker, and then make it impossible for them to proceed (being impossibly critical of their writing, for example), that’s just as bad, in most of the same ways.

Saying yes to everything

You’re not made of time, any more than you’re made of money. If people are asking questions with well-documented answers, you should refer those people to those answers, as a solution, but also as a reason for why that trade would not have been worth your time.

If you don’t respect your time, nobody else will, either.

Inaccessibility

Always be accessible via the browser or email. If you’re primarily available via IRC, make sure to provide a link in your project that uses a web-based IRC client, so people can ask you questions without leaving their browser. If your wiki is this weird non-HTTP obscure thing, make sure their are browser clients for it that can access the docs.

A good man page is not good enough, if I can’t find the contents by googling “$projectname man page”.

Make sure that all recorded answers are able to be indexed by the major search engines. Data that cannot be found is lost to the world, I don’t care if you know where to find it if nobody else can.

Basically, you never want to put yourself or your knowledge ecosystem more than thirty seconds away from the user, who may not have any special software installed, may be on an old and shitty mobile platform, and so on. These kinds of artificial barriers push potential contributors away, before they ever have a chance to discover how awesome your software is.

Conclusion

Write The Fucking Manual is like the GPL of social agreements - it aggressively promotes open knowledge, in an environment where knowledge is often freeloaded, unrecorded, or silently withheld. It makes the most out of your community, and promotes organic growth. It delegates the load of knowledge distribution, allowing the developers to spend more time developing (but also pushing them to rubber-duck analyze their own designs, explaining code architecture at a more meaningful level). It fosters ownership stake in projects, mutual respect, and deep understanding among a much larger group of people.

It’s friendlier than RTFM, more productive, and makes things easier to google. What’s not to love?