grokking the paradigm: why i get confused (and what i’m doing about it)
Post on 11-Jan-2016
30 Views
Preview:
DESCRIPTION
TRANSCRIPT
© 2006 EMC Corporation. All rights reserved.
Grokking the Paradigm:Why I Get Confused(and what I’m doing about it)
Dennis Dawson
Principal Technical Writer
EMC/Documentum
Grokking the Paradigm 2© 2006 EMC Corporation. All rights reserved.
Ten Minutes’ Worth of Stuff
• 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
Grokking the Paradigm 3© 2006 EMC Corporation. All rights reserved.
What the...?
Multiplicitas componatisres simplex*
Bacchus Filius Aurorae
*Complexity is composed of simple things.
Grokking the Paradigm 4© 2006 EMC Corporation. All rights reserved.
What the...?
If you can’t explain something simply, you
don’t understand it well enough.
Albert Einstein
Grokking the Paradigm 5© 2006 EMC Corporation. All rights reserved.
What the...?
Magic is easy, once YOU
know the secret!
Marshall Brodien
Grokking the Paradigm 6© 2006 EMC Corporation. All rights reserved.
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© 2006 EMC Corporation. All rights reserved.
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© 2006 EMC Corporation. All rights reserved.
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© 2006 EMC Corporation. All rights reserved.
Why Am I Confused?Words Have Meaning
• 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)
“You keep using that word – I do not think it means what you think it means.”
-Inigo Montoya, The Princess Bride
Grokking the Paradigm 10© 2006 EMC Corporation. All rights reserved.
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© 2006 EMC Corporation. All rights reserved.
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© 2006 EMC Corporation. All rights reserved.
Ways We’re Addressing These IssuesEmbedded Documentation
For D6, documentation is now embedded in• Configuration files• TLD files• Improved Javadocs
Grokking the Paradigm 13© 2006 EMC Corporation. All rights reserved.
Ways I’m Addressing These IssuesUsage Examples
• Short examples• Practical examples• Alternative examples • One concept per example
© 2006 EMC Corporation. All rights reserved.
Clarifications/comments?Please send them to:
dawson_dennis@emc.com
WDK Questions? Please visit:http://developer.emc.com/developer/
top related