

RTFC is the New RTFM - jradakov
http://jakeradakovich.wordpress.com/2013/04/24/rtfc-is-the-new-rtfm/

======
spartango
This worries me a little, because it cuts against the ideas of abstraction
that are central to most software engineering.

Don't get me wrong, I'm not against reading the code if and when it is
available.

I just worry that reliance on this MO goes against the idea that you can
specify a programming interface for your system and people can develop against
that without knowing the implementation. This is rather powerful in working
with other people, complex systems, and systems that are changing, where
reading the code may become inefficient.

I'd push back on the mindset of RTFC by saying that as a developers we should
try not to link ourselves to infrastructure for which RTFM fails. I know it
biases my search for libraries.

> I realize complaining about the lack of documentation in some open source
> projects is like complaining that there is no foie gras at a friend’s free
> dinner party

I'd argue that docs aren't foie gras, and not having them is like having a
compile error/obvious segfault in your code. Just like stability, docs matter.

~~~
sophacles
On the other hand, I out of hand reject libraries for which code is not
available, unless forced by employers to do otherwise. Documentation is great,
but at the end of the day, I still will throw a spike, no matter how good the
documentation is. Similarly, I will look at the code to understand how the
authors do an abstraction. It isn't to tie my code to something, it is to find
out where the abstraction stops working. My applications aren't that special,
and not tied to the code, but if I don't understand how something works, I
can't wrap my head around how to utilize it properly.

Simply put: I'm going to write my own wrapper for just about any external code
anyway - my internal API can then be changed on the backend to use new
libraries, rather than changing all my code. I will do this anyway, because
rarely is a new library a drop-in replacement for an old library. This, not
avoiding an understanding of the code details, is how you keep yourself
independent of implementation.

------
kaffeinecoma

      I nonchalantly told him to look at the source code of the library
      we were using. He looked at me like I had asked him to help me dig up a grave.
    

I can't imagine not examining the source code of the various frameworks I use
on a daily basis.

I think the next time I interview a candidate I will ask them what major open-
source libraries they use. Then I will ask them what they think of the quality
of the source code, how it's implemented, what they find difficult to reason
about, etc. Getting a blank stare at this point will be a kind of FizzBuzz
moment.

Edit: I'm not suggesting that candidates should be an expert on the internals
of the libraries they use (I'm certainly not). What I'm looking for is the
ability to crack them open when you hit a wall.

~~~
tych0
I think it also depends on the language too. In languages with more expressive
type systems, you can usually make an educated guess about something based on
the type signatures it has. For the dynamic languages, though, reading the
code is an absolute must.

~~~
tterrace
It definitely depends on the language. The author mentions spring security so
I'm assuming he's using java, where it's a massive PITA to manually hunt down
and attach the sources to the 50 jars you have in lib/. Maven probably has
something that will automatically do this but if your legacy project is just
using ant then you're pretty much stuck.

~~~
jradakov
Java is exactly what I'm using, and you are correct... it is a massive PITA to
attach sources. Unfortunately, we're not using Maven but plan to in the
future.

~~~
tterrace
If you're using eclipse, I found this plugin helps a bit:
<http://marketplace.eclipse.org/content/java-source-attacher> . For most
popular jars you can just right click and hit "attach source".

------
jerrya
Yes, projects that claim to be infrastructure and come with no documentation,
and presumably few comments, and who knows what unit tests.

It would be an exaggeration to refer to that as minimally viable code (mvc).
It is really only a statement of the lack of engineering actually being
practiced, and makes me wonder about the lack of robustness, the lack of
security, the numbers of bugs in the systems produced.

I am not certain this is a winning strategy for open source.

~~~
astrodust
Something needs to be done to address this enormous problem.

One of the worst examples I've come across lately is Zookeeper
(<http://zookeeper.apache.org/>), which should win an award for how
confusingly useless the documentation is. The Java source is probably
refreshingly concise.

------
pothibo
I think thoughtful, detailed guides on how to browse/use code is better than
code documentation.

Too often (mostly in interpreted language), I see a method that takes a hash
as an option and I see that option being passed down to 3, 4 or more different
functions. So in order to know what options are available for a given method,
you have to browse through all the other methods that takes the same hash as
argument.

I haven't seen a framework dealing with that through documentation. Some are
better than others, but they never cover everything.

------
nkuttler
<http://catb.org/jargon/html/R/RTFS.html>

~~~
wereHamster
How far we've gone. First RTFB, then RTFM, now RTFS/C. What's next? RTF{Minds
Of The People Who Wrote The Code}?

~~~
jradakov
I agree (hence the post), but at least with open source we have access to the
source code. I realize this doesn't replace documentation, but could you
imagine using a closed source project with sh __*y documentation?

------
duwease
I've been bitten by open-source AND closed-source applications recently, from
different angles.

Once when using an Adobe application that was behaving erratically, and I was
unable to see what was happening internally for myself (and obviously the
behavior wasn't documented). Incredibly frustrating, and no recourse except to
hack around it and hope it didn't mutate.

More recently, I've been bitten by a fairly popular open source application
that I intended to use without modification (just configuration). But the
documentation was so awful that I couldn't even figure out how to configure
it. Ultimately, I had the recourse of stepping through the code to figure it
out, but when you're trying to build adoption of your application, it would
make sense to make it usable for its main purpose without setting up the
actual source code in a debugger.

One interesting generalization I see is that the user-friendliness and
documentation of the open-source app correlates quite often to the language
used. PHP and Ruby projects seem to be built with an eye towards helping the
eventual users use it. The Java projects, while often more competently written
and complicated, seem to often be presented as code-only, take it or leave it,
user-friendliness be damned.

------
gyepi
I have noticed the increasing paucity of documentation in many open source
projects. In the past, this would annoy me when I had to context switch from a
perfectly good flow state to a documentation reading state. However, I
realized that I was doing it wrong; it meant that I was not spending enough
time analyzing the code I was about to "adopt" and depend on for my project.
Now, I read the documentation and source code for every open source program
before I choose to use it. I also find correlations between the quality of the
code and the documentation; good quality code sometimes lacks documentation
but poor quality code rarely has good documentation.

Reading the code also provides the opportunity for learning beyond the
documentation; there's a wealth of really good code out there just waiting to
be read.

~~~
bttf
I can agree with this. There have been times when I thought I understood the
concept of something after reading the documentation, only to find myself
gaining a deeper understanding when reading the code.

------
ghshephard
One organization that I worked at had a firmware team that moved quickly, and
wrote the interface layer to the PHY/MAC/Network devices. After they defined
the interface, later on enterprise software teams, and utility software teams,
would write the "User Friendly" tools that would be used to configure the
networking devices, but the firmware team did write a tiny "shim" utility that
they released with firmware, that could be used to control the firmware at a
very raw/native level.

Whenever you were wondering what parameters to pass to this low level (very
useful) utility, the answer was almost always, "Just check out the Code" - and
answer that was actually surprising straightforward once you got used to it.

------
greenyoda
" _I realize complaining about the lack of documentation in some open source
projects is like complaining that there is no foie gras at a friend’s free
dinner party_ "

Actually, it's more like not having _chairs_ at a dinner party. It's a
significant discomfort, not a lack of a luxury.

 _"The Spring Security documentation says it best…

It is much easier to debug your application or to work out where a problem
lies if you don’t treat the external code you are working with as a black box
which you never look inside. The first thing you should do when an exception
you don’t understand is thrown from an open source library is jump to the
class and line number and take a look to figure out what the code was doing
there. Otherwise you’re missing out on much of the benefit of using open
source code."_

Sorry, but it's a lot easier to debug your application if you have
documentation that tells you under what conditions the library throws a
particular exception.

Having to understand the source code of a library to be able to figure out its
behavior eradicates much of the benefit of using a library in the first place.
And the average product these days relies on so much open source software that
you can't possibly have the time to dig through the sources to solve every
little problem. Would the author of this statement be happy if he had to dig
through Linux kernel code, or Apache web server code, or the code of the
dozens of Java libraries that Spring is dependent on? I don't think so.

------
jamieb
I'm using Spring 3.1, Jetty, various OWASP, guava. I am in the code of Spring
and Jetty on a daily basis, and OWASP when I first used it. I learned guava by
writing unit tests to verify my assumptions - assumptions I learned from the
documentation - and which turned out to be wrong in key aspects.

Documentation is ambiguous, and even documentation which is unambiguous is
often wrong (or perhaps more kindly, "out of date").

------
stox
I always preferred UTSL ( Use The Source, Luke ), instead of RTFC.

