Grokking the Paradigm: Why I Get Confused (and what I’m doing about it)

1. Grokking the Paradigm:Why I Get Confused(and what I’m doing about it) Dennis Dawson Principal Technical Writer EMC/Documentum

2. Here’s what I’m gonna talk about: Warm up quotations Why I get confused (and why I’m not surprised) How I’m addressing my concerns Ten Minutes’ Worth of Stuff Grokking the Paradigm

3. What the...? Multiplicitas componatisres simplex* Bacchus Filius Aurorae *Complexity is composed of simple things. Grokking the Paradigm

4. What the...? If you can’t explain something simply, you don’t understand it well enough. Albert Einstein Grokking the Paradigm

5. What the...? Magic is easy, once YOUknow the secret! Marshall Brodien Grokking the Paradigm

6. BTFM • You may be familiar with the acronym RTFM (read the fabulous manual) • If you’ve read our documentation and you still don’t know what to do next, I suggest you BTFM (blame the fabulous manual) Grokking the Paradigm

7. Why Am I Confused?Nothing Does Anything • Taken out of context, nothing does anything • Abstraction • Re-use • Automagic Triggers • Nothing does anything by itself • Components are interrelated and multilayered • Behavior is isolated from the interface • Commands are often redirected Grokking the Paradigm

8. Why Am I Confused?Backward Compatibility • Backward compatibility is a double-edged sword • Standards change quickly • Customizations migrate slowly • Some things that were originally donefor a very good reason are no longernecessary, but can’t be revised. Grokking the Paradigm

9. Why Am I Confused?Words Have Meaning “You keep using that word – I do not think it means what you think it means.” -Inigo Montoya, The Princess Bride • The terms in use made sense at the time they were created • Names can be redundant, misleading • Some represent two colliding ideas: firePreSubmitClientEvent (postServerEvent.GENERIC_PRE_SUBMIT) Grokking the Paradigm

10. Why Am I Confused?Some Words Have No Meaning • Frequent use of self-referential variables • Arguments passed in a string array called “args” • Often the pertinent information you want is one of the “args” • No way of knowing what the values are/should be without tracing through the logic • No way of knowing whether the arguments are significant until you trace through the programming logic postServerEvent( null, null, null, "onClickObject", "objectId", id, "type", type, "isFolder", isFolder); } Grokking the Paradigm

11. Ways I’m Addressing These IssuesMinimalism • Few people read documentation • Minimalist documentation provides just enough information to allow a user to solve a problem and continue working • Done properly, users learn faster and show better retention Grokking the Paradigm

12. Ways We’re Addressing These IssuesEmbedded Documentation For D6, documentation is now embedded in • Configuration files • TLD files • Improved Javadocs Grokking the Paradigm

13. Ways I’m Addressing These IssuesUsage Examples • Short examples • Practical examples • Alternative examples • One concept per example Grokking the Paradigm

14. Clarifications/comments?Please send them to:dawson_dennis@emc.comWDK Questions? Please visit:http://developer.emc.com/developer/