rbowen · April 21, 2025 18:32 · May 5, 2015 · May 5, 2015 · May 5, 2015 · May 5, 2015
diff --git a/rtfm.md b/rtfm.md
@@ -12,7 +12,7 @@ First, I'd recommend [Conversation and Community](http://www.amazon.com/Conversa
 
 The title of this essay comes from Kathy Sierra, who in a presentation years ago had the slide shown above, reading "If you want them to RTFM, make a better FM." But how do we go about doing that?
 
-There's common wisdom in the open source world - everybody knows that the documentation is awful, that nobody wants to write it, and that this is just the way things are. But the truth is that there's **lots** of people that want to write the docs. We just make it too hard for them to participate. So they write articles on Stack Overflow, on their blogs, and on third-party forums. While this can be good, it's also a great way for worst-practice solutions to bloom and gain momentum. Embracing these people and making them part of the official documentation effort for your project has many advantages.
+There's common wisdom in the open source world - everybody knows that the documentation is awful, that nobody wants to write it, and that this is just the way things are. But the truth is that there are **lots** of people that want to write the docs. We just make it too hard for them to participate. So they write articles on Stack Overflow, on their blogs, and on third-party forums. While this can be good, it's also a great way for worst-practice solutions to bloom and gain momentum. Embracing these people and making them part of the official documentation effort for your project has many advantages.
 
 Unlike writing fiction, where the prevailing advice is "just start writing", when it comes to technical writing you need to plan a bit. There's several questions that you should ask before you start.
 

diff --git a/rtfm.md b/rtfm.md
@@ -80,10 +80,24 @@ A large part of your audience only cares about solving their immediate problem,
 
 So it's critical that examples have been tested. No matter how trivial an example is, you must test it and make sure it does the expected thing. Many frustrating hours have been spent trying to figure out why an example in the docs doesn't work, when a few minutes of testing would have revealed that a colon should have been a semicolon.
 
-Recipes should also promote the best practice, not merely the simplest or fastest solution.
+Recipes should also promote the best practice, not merely the simplest or fastest solution. And never tell them how *not* to do it, because they'll just cut and paste that, and then be in a worse fix than when they started.
 
 One of my favorite websites is ["There, I Fixed It"](http://failblog.cheezburger.com/thereifixedit), which showcases the ingenuity of people who solve problems without giving much thought to the possible ramifications of their solution - they just want to solve the problem!
 
+### Error messages
+
+Yes, error messages are documentation, too. Helpful error messages which actually point to the solution save countless hours of hunting and frustration.
+
+Consider these two error messages:
+
+`ERROR. FORBIDDEN`
+
+and
+
+`Access forbidden by file permissions. (ERRNO 03425)`
+
+The first is alarming, but unhelpful, and will require a great deal of poking around to figure out why it was forbidden. The second tells you that it has to do with file permissions, and has the added benefit of an error number which you can Google for the many articles that detail how to fix the problem.
+
 # Philosophy
 
 This entire line of thought came out of years of enduring technical support channels - IRC, email, formal documentation, Usenet, and much more.
@@ -92,18 +106,15 @@ We, those who Hold The Answers, seem to want to make it hard for the new guy. Af
 
 The the technology world is getting more complicated every day. The things that you're expected to know grow all the time, and nobody can be an expert in everything. Expecting that everyone do all of their homework and ask "smart questions" is not merely unreasonable, it's becoming impossible.
 
-## Solutions
-
-## Why we make it hard for them
-
-## Diligence, Patience, and Humility
+Compassionate tech support, and better documentation, is the only way for people to effectively use your software. And, if they can't get their answers in a reasonable amount of time, they'll use a different solution that has a better paved onramp.
 
+Years ago, Larry Wall, the creator of the Perl language and father of that community, gave a talk about the three virtues of a programmer - Laziness, Impatience, and Hubris. It is [well worth reading](http://c2.com/cgi/wiki?LazinessImpatienceHubris), but it must be remembered that these are the virtues of a programmer, in their role as a programmer, relating to a computer. As a person, relating to other people, he said in his address at the same conference the following year, Diligence, Patience, and Humility are the three virtues we should aspire to.
 
-Don't tell them how not to do it.
+In helping people with their technical problems, impatience is perceived as arrogance. "My time is more important than your problem." Hubris is perceived as belittling. And laziness? Well, that's just laziness.
 
-Don't make them feel stupid: This must be a core goal
+Being patient and kind, helping people move at their own pace, even when it feels slow, is perceived as respect. Welcoming people at whatever level are, and patiently helping them move to the next level, is how you build your community.
 
-Error messages are also documentation
+Don't make people feel stupid: This must be a core goal.
 
 Even if everyone else in the world is a jerk, you don't have to be.
 
diff --git a/rtfm.md b/rtfm.md
@@ -52,24 +52,45 @@ The first thing you have to decide (and, yes, you need to decide this, because t
 
 For example, on the Apache Web Server documentation, we have a document called Getting Started - http://httpd.apache.org/docs/current/getting-started.html - which covers what you need to know before you get started. The goal of the document is to draw a line saying what is outside of the scope of the documentation, while also pointing people to resources that do in fact cover those things in great depth. Thus, the HTTP specification, the inner workings of DNS, and content matters such as HTML and CSS, are firmly outside of the scope of the documentation, but everyone using the Apache Web Server needs to know these things.
 
+## Types of docs
 
+Once you've determined the scope, and who you're writing to, there are several different kinds of documents that you can write for them. Anne Gentle categorizes them thus:
 
-* Start Here
-* Reference Guide
-* Tutorials
-* Learning/Understanding
-* Cookbook/Recipe 
-(Anne Gentle)
+### Start Here
 
-REFERENCE MANUAL
-Comprehensive and exhaustive
-Correct
-Consistent format
-Best practice
-Lots of examples
-All examples must be tested
+Like the "Getting Started" document I mentioned a moment ago, this is the place where you tell them what they need to know before they even get started.
 
-# How
+### Reference Guide
+
+The reference guide is comprehensive and usually pretty dry. This is where terms are defined, functions input and output are explained, and examples are given. The tone is very factual and to the point. There's not much discussion, or "conversation". The voice is usually impersonal.
+
+### Tutorials
+
+Tutorials hold your hand and lead you down the path. They show you each step, and occasionally sit down on a bench by the path to explain the rationale for a particular step. They are very conversational - sometimes even chatty. The voice is personal - you are speaking to a particular person, defined in the earlier persona phase.
+
+### Learning/Understanding
+
+Often linked to from the tutorials, the learning/understanding documents dig deeper. They investigate the why and the how of a particular thing. Why was a certain decision made? How was it implemented in the code? What does the future look like for this thing? How can you help create that future. These documents are sometimes better done as blog posts than as part of the formal documentation, as they can be a serious distraction to people that are just trying to solve a problem.
+
+### Cookbook/Recipe
+
+There's a reason that the Cookbooks are often the best selling part of the OReilly technical book catalog. People want solutions, and they want them now. The recipe, or cookbook section of your document should provide cut-and-paste best-practice solutions to common problems. They should be accompanied by an explanation, but you should understand that most of the cookbook users will cut and paste the solution, and that'll be the end of it for them.
+
+A large part of your audience only cares about solving their immediate problem, because that's all they're getting paid to do, and you need to understand that this is a perfectly legitimate need. When you assemble your new Ikea desk, you don't care *why* a particular screw size was selected, you just want the instructions, and you expect them to work.
+
+So it's critical that examples have been tested. No matter how trivial an example is, you must test it and make sure it does the expected thing. Many frustrating hours have been spent trying to figure out why an example in the docs doesn't work, when a few minutes of testing would have revealed that a colon should have been a semicolon.
+
+Recipes should also promote the best practice, not merely the simplest or fastest solution.
+
+One of my favorite websites is ["There, I Fixed It"](http://failblog.cheezburger.com/thereifixedit), which showcases the ingenuity of people who solve problems without giving much thought to the possible ramifications of their solution - they just want to solve the problem!
+
+# Philosophy
+
+This entire line of thought came out of years of enduring technical support channels - IRC, email, formal documentation, Usenet, and much more.
+
+We, those who Hold The Answers, seem to want to make it hard for the new guy. After all, we walked uphill in the snow to school, and back, with bare feet. We figure out how to do this by reading the code and experimenting. Why should we make it any easier for these kids? They should be made to *earn* it, same as we did, right?
+
+The the technology world is getting more complicated every day. The things that you're expected to know grow all the time, and nobody can be an expert in everything. Expecting that everyone do all of their homework and ask "smart questions" is not merely unreasonable, it's becoming impossible.
 
 ## Solutions
 

diff --git a/rtfm.md b/rtfm.md
@@ -50,7 +50,8 @@ On to the mechanics. What should you be writing?
 
 The first thing you have to decide (and, yes, you need to decide this, because there's not necessarily one right answer) is what your document scope is. That is, what topics are you willing to cover? The implication, of course, is that everything else is out of scope, and should be pushed to someone else's documentation.
 
-For example, ...
+For example, on the Apache Web Server documentation, we have a document called Getting Started - http://httpd.apache.org/docs/current/getting-started.html - which covers what you need to know before you get started. The goal of the document is to draw a line saying what is outside of the scope of the documentation, while also pointing people to resources that do in fact cover those things in great depth. Thus, the HTTP specification, the inner workings of DNS, and content matters such as HTML and CSS, are firmly outside of the scope of the documentation, but everyone using the Apache Web Server needs to know these things.
+
 
 
 * Start Here

diff --git a/rtfm.md b/rtfm.md
@@ -1,4 +1,4 @@
-*Definition*: **RTFM** - *Read The F* Manual*. Occasionally it is ironically rendered as *Read The Fine Manual*. A phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.
+*Definition*: **RTFM** - *Read The F'ing Manual*. Occasionally it is ironically rendered as *Read The Fine Manual*. A phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.
 
 Have you noticed that the more frequently a particular open source community tells you to RTFM, the worse the FM is likely to be? I've been contemplating this for years, and have concluded that this is because patience and empathy are the basis of good documentation, much as they are the basis for being a decent person.
 

diff --git a/rtfm.md b/rtfm.md
@@ -1,4 +1,4 @@
-*Definition*: **RTFM** - Read The F* Manual. Occasionally it is ironically rendered as Read The Fine Manual. A phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.
+*Definition*: **RTFM** - *Read The F* Manual*. Occasionally it is ironically rendered as *Read The Fine Manual*. A phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.
 
 Have you noticed that the more frequently a particular open source community tells you to RTFM, the worse the FM is likely to be? I've been contemplating this for years, and have concluded that this is because patience and empathy are the basis of good documentation, much as they are the basis for being a decent person.
 
@@ -36,17 +36,22 @@ In this [example from the PHP docs](http://php.net/strpos), the English saying,
 
 The next question to ask is "where?" Yes, you need to have documentation on your project website, but where else is the conversation already happening? Except in very rare cases, other sites like (StackOverflow](http://stackoverflow.com/) are the de facto documentation for your project, and if you care about actually helping your users, you need to go to where they are. If they're asking questions on Twitter, Facebook, or AOL, you need to go there, and answer their questions there, always giving them pointers back to the official documentation so that they know where to look next time.
 
-# What?
+You can't control where people are having their conversations, and attempts to do so will be seen as being out of touch with your audience. (While we're on the topic, they're not "your" audience anyway.)
 
-## Solutions
+Once, at a former employer, it was discovered that "our audience" was having their conversations on Facebook, rather than on our website. Those in power decided that we had to stop this, and we put up our own internal social site, and told everyone that they had to use it, rather than Facebook, when discussing our organization. I suspect you can guess how well that worked out for us.
 
-## Why we make it hard for them
+But you're doing the same thing when you ignore the audience on StackOverflow, Twitter, and various third-party websites, because they're not in the right place.
 
-## Diligence, Patience, and Humility
+# What?
+
+On to the mechanics. What should you be writing?
 
 ## Scope
 
-# How
+The first thing you have to decide (and, yes, you need to decide this, because there's not necessarily one right answer) is what your document scope is. That is, what topics are you willing to cover? The implication, of course, is that everything else is out of scope, and should be pushed to someone else's documentation.
+
+For example, ...
+
 
 * Start Here
 * Reference Guide
@@ -63,6 +68,15 @@ Best practice
 Lots of examples
 All examples must be tested
 
+# How
+
+## Solutions
+
+## Why we make it hard for them
+
+## Diligence, Patience, and Humility
+
+
 Don't tell them how not to do it.
 
 Don't make them feel stupid: This must be a core goal

diff --git a/rtfm.md b/rtfm.md
@@ -1,4 +1,4 @@
-Definition: **RTFM** - Read The F* Manual. Occasionally it is ironically rendered as Read The Fine Manual. A phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.
+*Definition*: **RTFM** - Read The F* Manual. Occasionally it is ironically rendered as Read The Fine Manual. A phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.
 
 Have you noticed that the more frequently a particular open source community tells you to RTFM, the worse the FM is likely to be? I've been contemplating this for years, and have concluded that this is because patience and empathy are the basis of good documentation, much as they are the basis for being a decent person.
 

diff --git a/rtfm.md b/rtfm.md
@@ -1,4 +1,4 @@
-Definition: RTFM - Read The F* Manual. Occasionally it is ironically rendered as Read The Fine Manual. A phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.
+Definition: **RTFM** - Read The F* Manual. Occasionally it is ironically rendered as Read The Fine Manual. A phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.
 
 Have you noticed that the more frequently a particular open source community tells you to RTFM, the worse the FM is likely to be? I've been contemplating this for years, and have concluded that this is because patience and empathy are the basis of good documentation, much as they are the basis for being a decent person.
 

diff --git a/rtfm.md b/rtfm.md
@@ -8,7 +8,7 @@ Although I've been doing open source documentation for almost 20 years, I have n
 
 First, I'd recommend [Conversation and Community](http://www.amazon.com/Conversation-Community-Social-Web-Documentation-ebook/dp/B00C7CC4IA/), by Anne Gentle. And if you're looking for a conference about this stuff, there's two that I'd suggest - [Write The Docs](http://conf.writethedocs.org/) and [OpenHelp](http://openhelpconference.com/).
 
-*Kathy Sierra pic goes here*
+*Kathy Sierra pic goes here* http://boxofclue.com/presentations/betterfm/images/kathysierra.jpg
 
 The title of this essay comes from Kathy Sierra, who in a presentation years ago had the slide shown above, reading "If you want them to RTFM, make a better FM." But how do we go about doing that?
 
@@ -44,3 +44,30 @@ The next question to ask is "where?" Yes, you need to have documentation on your
 
 ## Diligence, Patience, and Humility
 
+## Scope
+
+# How
+
+* Start Here
+* Reference Guide
+* Tutorials
+* Learning/Understanding
+* Cookbook/Recipe 
+(Anne Gentle)
+
+REFERENCE MANUAL
+Comprehensive and exhaustive
+Correct
+Consistent format
+Best practice
+Lots of examples
+All examples must be tested
+
+Don't tell them how not to do it.
+
+Don't make them feel stupid: This must be a core goal
+
+Error messages are also documentation
+
+Even if everyone else in the world is a jerk, you don't have to be.
+
diff --git a/rtfm.md b/rtfm.md
@@ -34,4 +34,13 @@ In this [example from the PHP docs](http://php.net/strpos), the English saying,
 
 # Where?
 
-The next question to ask is "where?" Yes, you need to have documentation on your project website, but where else is the conversation already happening?
+The next question to ask is "where?" Yes, you need to have documentation on your project website, but where else is the conversation already happening? Except in very rare cases, other sites like (StackOverflow](http://stackoverflow.com/) are the de facto documentation for your project, and if you care about actually helping your users, you need to go to where they are. If they're asking questions on Twitter, Facebook, or AOL, you need to go there, and answer their questions there, always giving them pointers back to the official documentation so that they know where to look next time.
+
+# What?
+
+## Solutions
+
+## Why we make it hard for them
+
+## Diligence, Patience, and Humility
+
diff --git a/rtfm.md b/rtfm.md
@@ -14,3 +14,24 @@ The title of this essay comes from Kathy Sierra, who in a presentation years ago
 
 There's common wisdom in the open source world - everybody knows that the documentation is awful, that nobody wants to write it, and that this is just the way things are. But the truth is that there's **lots** of people that want to write the docs. We just make it too hard for them to participate. So they write articles on Stack Overflow, on their blogs, and on third-party forums. While this can be good, it's also a great way for worst-practice solutions to bloom and gain momentum. Embracing these people and making them part of the official documentation effort for your project has many advantages.
 
+Unlike writing fiction, where the prevailing advice is "just start writing", when it comes to technical writing you need to plan a bit. There's several questions that you should ask before you start.
+
+# Who?
+
+The first of these is "who?" Who are you writing to? Some professional tech writers create [personas](http://www.agiledocs.com/using-personas-user-documentation/) so that when they are writing, they can think to themselves "What would Monica need to know in this situation?", or "What kind of problem is Marcus likely to have around this topic?" and then write accordingly.
+
+It is critical, at this point in the process, to remember that not all of your audience are young white english-speaking men who grew up watching Monty Python.
+
+Exhibit A: The Python documentation (Include http://boxofclue.com/presentations/betterfm/images/monty.png here)
+
+Now, don't mistake me - the Python documentation, is, for the most part, awesome. But there's one complaint I have with it - the inside jokes. The Monty Python humor runs through all of the documentation, and this is a double-edged sword. Inside jokes form a sense of community, because you *get* the joke, and so you're on the inside. Except when you're not. In which case it points out starkly that you're not on the inside. Tread carefully here. Consider including a reference guide that explains the jokes, and, in the case of dead parrots, points to a [YouTube video](https://www.youtube.com/watch?v=4vuW6tQ0218).
+
+Similiarly with colloqialisms:
+
+Exhibit B: The PHP documentation (Include http://boxofclue.com/presentations/betterfm/images/haystack.png here)
+
+In this [example from the PHP docs](http://php.net/strpos), the English saying, finding a needle in a haystack, is referred to, in order to make this example more understandable. This is great if you are a native English speaker, in that it makes immediately obvious which argument is which. However, for those that are not, points out to them that they are not the target audience, which can have a chilling effect on bringing new people to your community.
+
+# Where?
+
+The next question to ask is "where?" Yes, you need to have documentation on your project website, but where else is the conversation already happening?
diff --git a/rtfm.md b/rtfm.md
@@ -1,2 +1,16 @@
 Definition: RTFM - Read The F* Manual. Occasionally it is ironically rendered as Read The Fine Manual. A phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.
 
+Have you noticed that the more frequently a particular open source community tells you to RTFM, the worse the FM is likely to be? I've been contemplating this for years, and have concluded that this is because patience and empathy are the basis of good documentation, much as they are the basis for being a decent person.
+
+First, some disclaimers.
+
+Although I've been doing open source documentation for almost 20 years, I have no actual training. There are some people that do, and there are some amazing books out there that you should read if you care about this stuff.
+
+First, I'd recommend [Conversation and Community](http://www.amazon.com/Conversation-Community-Social-Web-Documentation-ebook/dp/B00C7CC4IA/), by Anne Gentle. And if you're looking for a conference about this stuff, there's two that I'd suggest - [Write The Docs](http://conf.writethedocs.org/) and [OpenHelp](http://openhelpconference.com/).
+
+*Kathy Sierra pic goes here*
+
+The title of this essay comes from Kathy Sierra, who in a presentation years ago had the slide shown above, reading "If you want them to RTFM, make a better FM." But how do we go about doing that?
+
+There's common wisdom in the open source world - everybody knows that the documentation is awful, that nobody wants to write it, and that this is just the way things are. But the truth is that there's **lots** of people that want to write the docs. We just make it too hard for them to participate. So they write articles on Stack Overflow, on their blogs, and on third-party forums. While this can be good, it's also a great way for worst-practice solutions to bloom and gain momentum. Embracing these people and making them part of the official documentation effort for your project has many advantages.
+
diff --git a/rtfm.md b/rtfm.md
@@ -0,0 +1,2 @@
+Definition: RTFM - Read The F* Manual. Occasionally it is ironically rendered as Read The Fine Manual. A phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Definition: RTFM - Read The F* Manual. Occasionally it is ironically rendered as Read The Fine Manual. A phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.
No results found