Hey, I Can Do That! Learning jQuery by Teaching jQuery by Doing jQuery By Karl Swedberg
Introduction <ul><li>Obligatory joke about those who can’t do… </li></ul>
What Am I Talking About? <ul><li>The magic of discovering new things by explaining what you think you already knew </li></ul>
Why Bother Talking About It? <ul><li>jQuery’s success is not just a result of its exceptional code </li></ul>
Opportunities to Teach <ul><li>Official wiki:  http://docs.jquery.com </li></ul><ul><ul><li>Anybody  can improve the docum...
Rhetorical Considerations Rhetoric: (n.) The art of putting the right words in the right places to achieve an effect
Aristotelian Rhetoric <ul><li>Logos (reason, logic, etc.) </li></ul><ul><li>Ethos (credibility of speaker, etc.) </li></ul...
Embracing and Extending Aristotle <ul><li>S peaker </li></ul><ul><li>O ccasion </li></ul><ul><li>A udience </li></ul><ul><...
Speaker <ul><li>Who are you? </li></ul><ul><li>How well do people know you?  </li></ul><ul><li>How much do you want people...
What prompted the writing? <ul><li>Explicit vs. implicit prompts </li></ul>
Audience <ul><li>What is their level of expertise? </li></ul><ul><li>What is their relationship to you (the speaker)? </li...
Purpose <ul><li>What do you hope to achieve? </li></ul><ul><li>After the audience has read it, what do you want them to be...
Subject (and other stuff) <ul><li>Structure / outline </li></ul><ul><li>Code-to-prose ratio </li></ul><ul><li>Length </li>...
Tone <ul><li>Diction (a.k.a. choice of words) </li></ul><ul><ul><li>Can affect the level of formality </li></ul></ul><ul><...
Tone – First-person singular (“I”)  <ul><li>works well with narrative style </li></ul><ul><li>Use with past tense to tell ...
Tone – First-person plural (“we”) <ul><li>Good for walking through code </li></ul><ul><li>Inclusive pronoun draws readers ...
Tone - Second-person  (“you” [understood]) <ul><li>When used exclusively, implies a higher level of authority </li></ul><u...
The Blessing & The Curse of Documentation Writing <ul><li>Reputation, prestige </li></ul><ul><li>Overload, overwhelm, over...
Upcoming SlideShare
Loading in …5
×

Writing for Code - Learning by Teaching by Doing

1,264 views

Published on

Presentation given at jQueryCamp07 about writing documentation, blog entries, books, etc.

Published in: Education, Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,264
On SlideShare
0
From Embeds
0
Number of Embeds
29
Actions
Shares
0
Downloads
21
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Writing for Code - Learning by Teaching by Doing

  1. 1. Hey, I Can Do That! Learning jQuery by Teaching jQuery by Doing jQuery By Karl Swedberg
  2. 2. Introduction <ul><li>Obligatory joke about those who can’t do… </li></ul>
  3. 3. What Am I Talking About? <ul><li>The magic of discovering new things by explaining what you think you already knew </li></ul>
  4. 4. Why Bother Talking About It? <ul><li>jQuery’s success is not just a result of its exceptional code </li></ul>
  5. 5. Opportunities to Teach <ul><li>Official wiki: http://docs.jquery.com </li></ul><ul><ul><li>Anybody can improve the documentation. Open to the public </li></ul></ul><ul><li>Plugins </li></ul><ul><li>Blogs </li></ul><ul><li>Books </li></ul>
  6. 6. Rhetorical Considerations Rhetoric: (n.) The art of putting the right words in the right places to achieve an effect
  7. 7. Aristotelian Rhetoric <ul><li>Logos (reason, logic, etc.) </li></ul><ul><li>Ethos (credibility of speaker, etc.) </li></ul><ul><li>Pathos (emotional appeal) </li></ul>
  8. 8. Embracing and Extending Aristotle <ul><li>S peaker </li></ul><ul><li>O ccasion </li></ul><ul><li>A udience </li></ul><ul><li>P urpose </li></ul><ul><li>S ubject </li></ul><ul><li>Tone </li></ul>SOAPSTone
  9. 9. Speaker <ul><li>Who are you? </li></ul><ul><li>How well do people know you? </li></ul><ul><li>How much do you want people to know about you? </li></ul><ul><li>What can you get away with? </li></ul><ul><li>Consider citations (a.k.a. name dropping) </li></ul>
  10. 10. What prompted the writing? <ul><li>Explicit vs. implicit prompts </li></ul>
  11. 11. Audience <ul><li>What is their level of expertise? </li></ul><ul><li>What is their relationship to you (the speaker)? </li></ul><ul><li>Beware of Unintended Audiences </li></ul>
  12. 12. Purpose <ul><li>What do you hope to achieve? </li></ul><ul><li>After the audience has read it, what do you want them to be able to do? </li></ul><ul><li>Secondary purposes? </li></ul><ul><li>Ulterior motives? </li></ul>
  13. 13. Subject (and other stuff) <ul><li>Structure / outline </li></ul><ul><li>Code-to-prose ratio </li></ul><ul><li>Length </li></ul>
  14. 14. Tone <ul><li>Diction (a.k.a. choice of words) </li></ul><ul><ul><li>Can affect the level of formality </li></ul></ul><ul><ul><li>Watch out for polarizing terms </li></ul></ul><ul><li>Personal Pronouns have an effect on ethos (speaker’s credibility, etc.) </li></ul>
  15. 15. Tone – First-person singular (“I”) <ul><li>works well with narrative style </li></ul><ul><li>Use with past tense to tell a story, describe process </li></ul><ul><li>Can use the “slow reveal” </li></ul><ul><li>Can affect the humble-to-arrogant spectrum – in both directions </li></ul>
  16. 16. Tone – First-person plural (“we”) <ul><li>Good for walking through code </li></ul><ul><li>Inclusive pronoun draws readers in, comforts them, engages </li></ul><ul><li>Can create a welcoming tone </li></ul>
  17. 17. Tone - Second-person (“you” [understood]) <ul><li>When used exclusively, implies a higher level of authority </li></ul><ul><li>Dangerous </li></ul><ul><ul><li>can increase distance between speaker and audience </li></ul></ul><ul><ul><li>can seem patronizing, produce a pedantic tone </li></ul></ul><ul><li>Best when used in official documentation or when replying to a specific person about a particular issue </li></ul>
  18. 18. The Blessing & The Curse of Documentation Writing <ul><li>Reputation, prestige </li></ul><ul><li>Overload, overwhelm, overeverything </li></ul>

×