How to encourage new programmers to read documentation?

Question

New developers seem to have a hard time reading documentation. They either skip it entirely, or if they do read it they don't read it carefully. Conversely, I've never met a skilled developer who doesn't regularly and thoroughly inspect framework and API documentation.

Even here on Stack Overflow, a good percentage of questions are readily answered by someone quoting and linking to documentation.

• What prompted your "Ah ha!" moment to make you start reading documentation?
• What advice do you have to new programmers to help them critically read documentation?
• How can we better write and publish documentation to make it easier for beginners to find and understand?

Update

Some suggestions so far:

• Online documentation, especially generated documentation, should still follow SEO principles (the method name link_to_function is no where in this URL!).
• Documentation sites should provide site search (a la Google or with a custom search engine).
• Jargon-heavy documentation should link to explanatory pages.
• Documentation can be broken into tiers: executive summary, basics, and details. This approach helps give users enough information to know where to begin in the potentially overwhelming detailed section.
• Better documentation:
  • focuses on overviews, concepts, and tutorial aspects rather than arcane details which can be found in the source or in lower level documentation.
  • has been given the same care in both writing and reviewing as production code.
  • is concise.
  • is executable!

Edit

Related topics:

• Keeping code and specs in sync

Answer 1

In my experience, those who don't read doc simply don't know how to read(serach, reference etc) doc efficiently. I don't just gave them the link to read. Instead I show them why/how I find that link.

Answer 2

Probably the same thing that makes non-programmers fail first time at easy, intuitive tasks: they know they don't know, so they presume it's okay to act like a total idiot and not even attempt to solve the task.

Answer 3

1. They don't know all those fancy words in the documentation
2. Most documentation was written by people who shouldn't be allowed to
3. They want to solve a problem now. They are too impatient to read lots of stuff, especially since that "stuff" is not telepathic and doesn't seem to relate to what they need.
4. If you don't understand something without a manual, you won't understand it with, either.

I usually start to read documentation, when I'm really stuck (i.e. when Googling and SOing didn't turn anything up). But in my experience, it rarely helps. Maybe I work on too many insane problems :)

[EDIT] I think that a main issue is that we don't have good editors. Word is clunky and unreliable. I guess it's a hard problem since Microsoft spend several billion dollars on it in the past 20 years and they still didn't get it right.

Wikis are nice but you suddenly need a server and you can't make sure that your documentation doesn't have "hole" (i.e. stuff that you simply forgot or didn't mention because it's obvious to you).

As for slang, a documentation system should automatically create an index and I should be able to click on any word in the documentation to get all other places where it's used with the place where it's defined at the top.

It should allow to put markers into the source text so I can find all places where I refer to a certain idea. In IDEs, we have refactoring where I can rename something in all places. Or I can extract duplicate "code" to a single place. We need something similar for documentation which leads directly to AI - the tool must have a basic understanding of what I'm talking about.

Also, the tool should actively prevent people from becoming creative with language. This not a novel. If you have three sentences in a row that start with "The database", then that's not nice but the point is to get some information across.I

Answer 4

Warning: Unix-centric answer follows.

• What prompted your "Ah ha!" moment to make you start reading documentation?

It's a toss up between discovering just how much I could read about by just typing man 3 printf, and discovering how often I'll Google something and the first few results will just be a manpage in HTML format.

• What advice do you have to new programmers to help them critically read documentation?

I guess run ls -lR /usr/bin/share/man/ and see just how many manpages of information you already have and should search through before asking someone else to search for you.

• What should replace "RTFM" as a LMGTFY-like catchphrase to push documentation?

I have a certain fondness for RTFM and LMGTFY, so I can't suggest any alternatives.

Answer 5

Make the documentation a video. :)

Answer 6

My experience is the following.

1. Many folks want a "job aid" that summarizes the relevant points into a tidy chart.

   • Most technical documentation is very detailed with little usable overview or roadmap. Too much documentation is "reference". Not enough is "tutorial".

2. Many folks aren't in the habit of searching documentation. Really. Their education is often classroom-based or worse. By worse, I mean haphazard exploration. Look at the various "plzsendtehcodez" questions on SO -- some of them exhibit a profound lack of clue.

   • Most technical documentation is unsearchable. Proprietary documentation is "valuable" intellectual property. Even open source project documentation is not always searchable. Google returns a lot of hits; an open source project needs a "search this site" link on their documentation page.

   • Without overviews or tutorials, it's hard to know which section and which nugget of goodness actually matter.

3. Few programmers are answerable for documentation.

   • Since they aren't producers, they aren't consumers, either.

   • I think all software (all!) should have embedded documentation and that's the focus of at least one code review. If the embedded documentation doesn't make sense -- well -- the software probably harbors at least one hidden bug.

4. Most programmers want copy-and-paste examples. These are usually buried in the unit test code.

   • Perhaps the tutorial should be a set of comments embedded in a unit test.

Answer 7

In many cases, it's not product documentation they should read - it's books on the subject. A documentation author has the job of - documenting the product. The author of a book about a product has the job of explaining it.

If you want to learn about a product or technology, with the information being presented to you by one or more people who thought you'd learn it best that way, then read a book.

Unfortunately, I get the impression that schools don't teach kids to read anymore. I hope I'm wrong about that.

Answer 8

There's no easy way to do it. It has to come from the programmer himself(or herself). The reason why I would like to pour over the documentation when faced is a problem is so that when I can't find the answer, at least I know what to ask an expert and tell him what I know so far.

This is actually a time saver for me and when in the process of reading, there's also bits of information that you come across that might not help you right now, but certainly will in future.

I usually tell the new programmers the things which I wrote above and I'd cross my fingers and hope that they realize that there's no better way to learn about a system than to read the freaking docs.

Nowadays, most companies have their own internal wiki where programmers would update whatever features they just did complete with code explanation so that in the long run, other programmers could read the info when they need improve upon that feature.

Answer 9

Tell them "Just read the documentation."

Answer 10

My experience is that we hate documentations. We sometimes prefer in finding out things ourselves. But sometimes, minimizing the contents also helps and summarize the items in form of bullets and numbers usually catches our attention.

Answer 11

We're so used to things being intuitive and user-friendly, we expect that same behaviour from things that may require some reading before understanding.

In other words, some things might not be as easy as you wish them to be. Diving into a framework or new language, without thinking or reading, reflects that expectation.

Encouraging new programmers to read the documentation starts with letting them realize not all things are suitable for consumerish intuitivity and require knowledge.

Answer 12

I don't think there are two types of people, those who have learned to read docs and those who haven't. It depends on your task, mood, time-frame, etc.

A better question is, why does your workplace require so much documentation to be understood? Investigate your processes and code base, and see if they can be made more self-evident and clearer. If necessary, they can be self-documenting, but this is already a failure mode.

Make imminent failure less harmful, and make it harder to screw things up, and people will learn the way most people learn best: learning by doing, in a safe environment. Provide a sandbox where people can explore.

Answer 13

The documentation must be easy accessible.

It must be up-to-date.

It's always easier to read it when you know where is it.

Answer 14

I find this is the best approach:

• Make top level documentation very simple - don't complicate it with detail. A simple overview of the software/API/whatever it is you're trying to document. The purpose of this document is to introduce general architecture/paradigms/concepts/language/lexicon used. Sort of a "My software in a nutshell" or "Learn my software in 24 hours".

• Make a lower level document that goes into more detail, but isn't necessarily detailed. This will allow someone to skip through the document without missing major points because they're overly bogged down in detail. Consider this an architectural overview of each of the components - once again, don't get bogged down in the details. This is the "Teach yourself X in 21 days" style document. It goes into more detail but is still a way off from overwhelming you with a whole load of currently irrelevant information.

• Technical document that breaks down to a lower level - this is the actual API document.

Admittedly the reader has potentially read the same things 3 times, but effectively by the time they're done the top level document, they understand what you're talking about without knowing any of the inside details. If you need them to get something done, they know where to look to figure out what you're talking about - they can gloss through the 2nd level document looking for what you're talking about, and then when they've found the correct component, they can drill into the 3rd level document for the details.

Much like a hierarchical search...

As a developer trying to find the discipline to read the documentation on countless amounts of technologies, you have to ask yourself - what stops me reading the documentation? The answers I come up with are these:

• More often than not, I don't know what to search for because I don't have a keyword. I don't have a keyword because I don't know what to search for. So where do I start? If I understand the techology from the top down, I theoretically should know what keywords to look for which solves the problem, but frequently we're learning it from the bottom up which doesn't allow for this.

• There is usually no middle level documentation, it is either too high level targetted at someone who has absolutely no experience with what they're trying to do, or so low level that what I'm looking for is heavily embedded in so much detail that I can't see the forest for the trees. Obviously the high level targeted at a beginner is next to useless for solving issues, but the detailed document is so low level that unless you know exactly what you're looking for, it's hopeless.

• The documentation is of a form that is not easily searchable. You can't ask documentation a vague question and have it say - "Oh, you need to try using X class for that" or "Have you tried looking at the visitor pattern?", which is usually enough to point you on the right direction. Once again, you need to ask specifics.

• There's no time alotted for reading documentation. You're given a problem, told to solve it "yesterday!" and the quickest way to an answer, and thus a solution is to ask someone else, be it a co-worker, a friend or the larger programming community - i.e. StackOverflow.

Something that we humans are great at that computer systems are really bad at is interpreting meaning by reading between the lines. I can ask a question and you can figure out - "Oh, he really meant this, not that" and give me the answer based on that interpretation. Consequently, while there's people to ask questions, they're always going to get asked questions more than the books/documentation are going to be read. This is a fact of life, and until someone invents a search system that can interpret semantic meaning from literal words, we'll hear the mnemonics RTFM and LMGTFY.

Answer 15

Where I work, I've taken to saying things like (to quote directly from you), "I've never met a skilled developer who doesn't regularly and thoroughly inspect framework and API documentation."

Honestly, it's often the case that if you point out what the most skilled people do, that's often sufficient. Those people who have it in them to become very skilled will go off and start doing those things, and the others... might be served by a different career.

Answer 16

Put all your documentation into intellisense. This is the only "documentation" I see most programmers reading anyways. Also, encourage people to write documentation for the code they write. If I write documentation myself, I am more likely to read someone else's (hopefully).

Answer 17

Mostly I think the problem is that the average usability of most documentation is nil.

It's not that YOUR documentation is necessarily bad, but when I approach a new document by an unknown developer, that's EXACTLY what I expect.

I learn to trust some sources over time--like Javadocs from Sun, pretty much always correct and always readable and always have the info you need.

If your docs are usable, I suggest that every time they come to you with a question that's in the docs, regardless of if you know it or not, you ask them to bring you their doc, highlight where it is and hand it back to them.

After a few of these they will learn to navigate your documentation.

Remember, a significant portion may be the fault of the documentation under question, not the developer. Perhaps YOU have learned to navigate some poorly indexed and arranged document to where you hardly know it's crap any more.

You might ask them why they had trouble finding the section they wanted and how you could improve the document to make navigating easier.

They should quickly become embarrassed enough to look before they approach you.