In REST there’s this rule: don’t save low-level links. Instead, start from the top and navigate the returned hyperlinks, as they may have changed. Detailed knowledge is transitory.
This same philosophy helps in daily programming work.
Say a bug report comes in: “Data is missing from this report.” My pair is more familiar with the reporting system. They say, “That report runs on machine X, so let’s log in to X and look at the logs.”
I say, “Wait. What determines which machine a report runs on? How could I figure this out myself?” and “Are all log files in the same place? How do we know?”
The business isn’t in a panic about this report, so we can take a little extra time to do knowledge transfer during the debugging. Hopefully my pair is patient with my high-level questions.
I want to start from sources of information I can always access. Deployment configuration, the AWS console, etc. Gather the context outside-in. Then I can investigate bugs like this alone in the future. And not only for this report, but any report.
“How can we ascertain which database it connected to? How can I find out how to access that database?”
“How can I find the right source repository? Which script runs it, with which command-line options? What runs that script?”
Perhaps the path is:
– deployment configuration determines which machine, and what repository is deployed
– cron configuration runs a script
– that script opens a configuration file, which contains the exact command run
– database connection parameters come from a service call, which I can make too
– log files are in a company-standard location
– source code reveals the rest.
This is top-down navigation from original sources to specific details. It is tempting to skip ahead, and if both of us already knew the whole path and had confidence nothing changed since last week, we might skip into the dirty details, go right to the log file and database. If that didn’t solve the mystery, we’d step back and trace from the top, verifying assumptions, looking for surprises. Even when we “know” the full context, tracing deployment and execution top-down helps us pin down problems.
Debugging strategy that starts from the top is re-usable: solve many bugs, not just this one. It is stateless: not dependent on environmental assumptions that may have changed when we weren’t looking.
REST as more than a service architecture. REST as a work philosophy.
After you gotntghe knowledge transferred from a peer do you feel there is any need for documentation such that other peersnwhen trying tonfind that out could refer to it. (With all the problems of docs it gets old nobody writes nobody reads especially it gets old inacurrate … . I too have the same doubts about docs. When reading your post I just asked myselfn would it be good to doc that knowledge transfer ? If so how? Google doc? Wiki? Mindmap? Forum? Mail? Local notes? Local wiki? Scala / java / clojure docs? 🙂