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

© 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


What the...?

Multiplicitas componatisres simplex*

Bacchus Filius Aurorae

*Complexity is composed of simple things.


What the...?

If you can’t explain something simply, you

don’t understand it well enough.

Albert Einstein


What the...?

Magic is easy, once YOU

know the secret!

Marshall Brodien


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)


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


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.


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


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);

}


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


Ways We’re Addressing These IssuesEmbedded Documentation

For D6, documentation is now embedded in• Configuration files• TLD files• Improved Javadocs


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:

[email protected]

WDK Questions? Please visit:http://developer.emc.com/developer/

Documents

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