lockcmpxchg wrote:
Something I should add is that in the workplace, we are encouraged to talk to each other and transfer the knowledge as fast as possible. It would be counter-productive to tell a new-hire to just go through all the company documentation to understand the product. Instead, he would be encouraged to do so, but we would also any questions he has when wanting to shortcut the documentation to start fixing bugs right away. We often feel that getting the new-hire to jump on bug-fixing and asking questions around is the easiest/fastest route.
Well... I think that is a sign that your documentation is not up to standards. IMHO.
For the software I am maintaining 9-to-5 (basically an interpreter for a domain-specific language), there are five pieces of documentation -- a developer guide on how to set up the dev environment, the internal structure of the project, how to build the software etc.; an general reference to the domain-specific language; two tutorials for the two different basic functionalities offered by it; and a reference for the DSL "library" offered with the software.
I would fully expect any newcomer to work through the developer guide to set up his system and get a rough understanding of the internals, then work through the tutorials to understand the product. He might ask questions when something is not clear, which I would take as a kind of bug report against the docs. But I will not sit down and walk him through introduction -- because that is what the developer guide and tutorials were written for. (The subject is quite involved, and I'd expect several weeks to go by before a newcomer got a grasp on "how things work". That would be weeks I'd be reduced to next to zero productivity if I were to walk him through. Not to mention the deficiencies of ad-hoc teaching, and the possibility of me being
not there for a walkthrough, due to illness, accident, or misplaning.)
And even later on, I would expect that documentation is consulted if there's a chance it might answer the question. E.g. "how does the extract() command work?" is right there in the docs. (And, actually, I would consult the docs myself before answering the question to avoid giving wrong info -- so why don't you do the lookup?) "Why doesn't extract() work here when the docs seem to imply it does?" is a very valid question, on the other hand.
Similar applies here, or at StackOverflow. A question of "I read that X is supposed to do Y, but this code here seems to indicate otherwise" is usually well-received. A question of "how does X work?" is not, with the LMGTFY pointer indicating that the information
is readily available, and that you should have checked before asking others to do the checking for you.
----
Besides, taking shortcuts into "fixing bugs" is a recipee for desaster, in my experience.