beginner friendly docs

Transcript

1. Improving Documentation with "Beginner's Mind" Karen Rustad
3. Documentation's six audiences and purposes:
4. Documentation's six audiences and purposes: 1.) First contact (new users)
5. Documentation's six audiences and purposes: 1.) First contact (new users) 2.) Education (new & existing users)
6. Documentation's six audiences and purposes: 1.) First contact (new users) 2.) Education (new & existing users) 3.) Support (experienced users)
7. Documentation's six audiences and purposes: 1.) First contact (new users) 2.) Education (new & existing users) 3.) Support (experienced users) 4.) Troubleshooting (pissed-off users)
8. Documentation's six audiences and purposes: 1.) First contact (new users) 2.) Education (new & existing users) 3.) Support (experienced users) 4.) Troubleshooting (pissed-off users) 5.) Internals (contributors)
9. Documentation's six audiences and purposes: 1.) First contact (new users) 2.) Education (new & existing users) 3.) Support (experienced users) 4.) Troubleshooting (pissed-off users) 5.) Internals (contributors) 6.) Reference (everyone)
10. Documentation's six audiences and purposes: 1.) First contact (new users) 2.) Education (new & existing users) 3.) Support (experienced users) 4.) Troubleshooting (pissed-off users) 5.) Internals (contributors) 6.) Reference (everyone)
11. Your most important docs:
12. Your most important docs: 1.) Installation/setup instructions
13. Your most important docs: 1.) Installation/setup instructions 2.) Tutorials
14. What makes a good tutorial good?
15. What makes a good tutorial good? 1. Advertises what's cool or unique
16. What makes a good tutorial good? 1. Advertises what's cool or unique 2. Enjoyable -- fun to read, not too long
17. What makes a good tutorial good? 1. Advertises what's cool or unique 2. Enjoyable -- fun to read, not too long 3. Consistently likely to succeed
18. What makes a good tutorial good? 1. Advertises what's cool or unique 2. Enjoyable -- fun to read, not too long 3. Consistently likely to succeed 4. Prepares reader for using it on their own
19. What makes a good tutorial good? 1. Advertises what's cool or unique 2. Enjoyable -- fun to read, not too long 3. Consistently likely to succeed 4. Prepares reader for using it on their own (These goals can conflict!)
20. What makes a good tutorial good? 1. Advertises what's cool or unique 2. Enjoyable -- fun to read, not too long 3. Consistently likely to succeed 4. Prepares reader for using it on their own
21. Newcomers use tutorials as a scaffold for building whatever they wanted to build using your project.
23. Our hypothetical tutorial-using user personas
24. Persona #1: Kira • CS undergrad • Familiar with Python, various libraries • Completely new to web dev • Has a web app idea she wants to build
25. Persona #2: Kevin • UX designer • Did a couple intro Python tutorials • Starting a new job using Django • Interested in getting more into development
26. Django tutorial runthrough
27. (note: some issues are no longer present in the current version of the tutorial!)
30. Django tutorial runthrough Bad installation hygiene
31. Django tutorial runthrough Bad installation hygiene Kevin: "Why wouldn't I just install everything site-wide?"
32. Django tutorial runthrough Create project "mysite"
33. Django tutorial runthrough syncdb
34. Django tutorial runthrough Development server
35. Django tutorial runthrough Debugging
36. Django tutorial runthrough Debugging Kevin: "My thing doesn't work. What do I do?"
37. Django tutorial runthrough Debugging Kevin: "My thing doesn't work. What do I do?" Kira: "None of my friends are Django developers... how can I get help?"
38. Django tutorial runthrough Create app "polls"
39. Django tutorial runthrough Projects v. apps
40. Django tutorial runthrough Projects v. apps Kevin: "My whole website is my web app, so it goes in one Django app, right?"
41. Django tutorial runthrough Apps pt. 2: Reusing others' apps
42. Django tutorial runthrough Apps pt. 2: Reusing others' apps Kira: "Other people write Django apps? That I can *reuse*? Sweet!"
43. Django tutorial runthrough Apps pt. 2: Reusing others' apps Kira: "Other people write Django apps? That I can *reuse*? Sweet!" Newcomers default to reinventing the wheel.
44. Django tutorial runthrough Apps pt. 2: Reusing others' apps Kira: "Other people write Django apps? That I can *reuse*? Sweet!" Newcomers default to reinventing the wheel. Poorly.
45. Django tutorial runthrough (list of files the app generator created)
46. Django tutorial runthrough Test-driven development
47. Django tutorial runthrough Test-driven development Kevin: "What's this tests.py thing for?"
48. Django tutorial runthrough Create models
49. Django tutorial runthrough Add app, syncdb again
50. Django tutorial runthrough Schema migrations: GOTCHA!
51. Django tutorial runthrough Schema migrations: GOTCHA! Kira: "What do you mean, I can't edit my frickin' models anymore? I ran syncdb, just like you said!"
52. Django tutorial runthrough Tutorial page 2: Admin, admin, admin
53. Django tutorial runthrough User-facing CRUD
54. Django tutorial runthrough User-facing CRUD Kira: "I'm not building a newspaper application. Why would I care about customizing the admin?"
55. Django tutorial runthrough Write URLs, write views
56. Django tutorial runthrough Write templates
57. Django tutorial runthrough User-facing CRUD
58. Django tutorial runthrough User-facing CRUD Kevin: "What kind of web app framework can't handle interactions and content from users?"
59. Django tutorial runthrough User-facing CRUD Kevin: "What kind of web app framework can't handle interactions and content from users?" If you don't tell newcomers a feature exists, many will assume it doesn't.
60. Django tutorial runthrough New version: form for poll voting
61. Django tutorial runthrough User-facing CRUD: Forms
62. Django tutorial runthrough User-facing CRUD: Forms Kira: "Handling form input by hand sounds possibly dangerous and definitely repetitious..."
63. Django tutorial runthrough User-facing CRUD: Forms
64. Django tutorial runthrough User-facing CRUD: Forms Kevin: "Okay, these ModelForms are kind of cool, I followed the docs and got one working, but I can't style them at all! I'll just write this form HTML by hand, that's easier."
65. Django tutorial runthrough User-facing CRUD: AJAX
66. Django tutorial runthrough User-facing CRUD: AJAX Kevin: "I don't want to have a separate URL and reload for every user function... what do I do?"
67. Django tutorial runthrough New version: Generic views
68. Django tutorial runthrough Fin
69. Django tutorial runthrough (https://docs.djangoproject.com/en/1.3/ intro/whatsnext/)
70. Django tutorial runthrough Static and media files
71. Django tutorial runthrough Static and media files Kevin: "How do I add CSS or images? How do my users add images? These go in different places? Huh?"
72. Django tutorial runthrough Template inheritance
73. Django tutorial runthrough Template inheritance Kira: "What, I shouldn't just create a stand- alone template file for every view?"
74. Django tutorial runthrough Template inheritance Kira: "What, I shouldn't just create a stand- alone template file for every view?" Kevin: "Thank *god*. Even PHP can do this."
75. Django tutorial runthrough Showing off
76. Django tutorial runthrough Showing off Kira: "I've never heard of this WSGI thing and I'd rather not fiddle with IPv6 for this.."
77. Django tutorial runthrough Showing off Kira: "I've never heard of this WSGI thing and I'd rather not fiddle with IPv6 for this.." Kevin: "I don't even know what those are."
78. "But most of these issues aren't pure *Django*... why should they be the Django tutorial's responsibility?"
79. What is the purpose of this tutorial?
80. What makes a good tutorial good? 1. Advertises what's cool or unique 2. Enjoyable -- fun to read, not too long 3. Consistently likely to succeed 4. Prepares reader for using it on their own
81. What makes a good tutorial good? 1. Advertises what's cool or unique 2. Enjoyable -- fun to read, not too long 3. Consistently likely to succeed 4. Prepares reader for using it on their own
82. Target audience: fairly experienced web developers who are already familiar with best practices and can cross-compare with other frameworks they've used
83. What makes a good tutorial good? 1. Advertises what's cool or unique 2. Enjoyable -- fun to read, not too long 3. Consistently likely to succeed 4. Prepares reader for using it on their own
84. Target audience: newcomers to web programming, ripe for indoctrination into the Cult of Django
85. Target audience: newcomers to web programming, ripe for indoctrination into the Cult of Django (mwa ha ha ha)
86. Is your goal to build a community, or just another library?
87. (either answer is perfectly okay!)
88. Comprehensive tutorials are possible!
89. Railsbridge (railsbridge.org) • Ruby • Rails • Git (GitHub) • Migrations (ActiveRecord) • Test-driven development (Cucumber) • Model-view-controller separation • User-facing CRUD operations • Deployment (Heroku) • Static files
90. PyStar (pystar.org) • Python • Django • Git (GitHub) • Migrations (South) • Test-driven development • MVC/MTV concepts • User-facing CRUD • Deployment (DjangoZoom)
91. Django for I Schoolers (bit.ly/xM1gmI) • Python • Django • Git (GitHub) • Migrations (South) • MVC/MTV concepts • Template inheritance • User-facing CRUD • AJAX • Static files • TDD • Authentication / app reuse
92. Disadvantage: Comprehensive tutorials are longer, more work to write (and to complete)
93. 1.) Modular structure can mitigate this (e.g. guides.rubyonrails.org)
94. 2.) Link to other people's tutorials, blog posts, other resources!
95. (even a link to a Google search is better than nothing)
96. Blind searching doesn't work well, so introduce as much lingo and concepts as you can (even just as links).
97. "Intro to Django" or "Intro to web programming using Django"?
98. "Intro to Django" or "Intro to web programming using Django"? Why not both?
99. Strategies / takeaways
100. Common issues in intro docs writing
101. Common issues in intro docs writing • Assuming familiarity with bash or filesystem architecture
102. Common issues in intro docs writing • Assuming familiarity with bash or filesystem architecture • Unstated assumptions about platform
103. Common issues in intro docs writing • Assuming familiarity with bash or filesystem architecture • Unstated assumptions about platform • List of directions without the "why"
104. Common issues in intro docs writing • Assuming familiarity with bash or filesystem architecture • Unstated assumptions about platform • List of directions without the "why" • Derelict command/code samples
105. Common issues in intro docs writing • Assuming familiarity with bash or filesystem architecture • Unstated assumptions about platform • List of directions without the "why" • Derelict command/code samples • No obvious place to ask for help
106. Strategies • We were all newbies once
107. Strategies "I notice I am confused."
108. Strategies Notice your own expertise and compensate accordingly.
109. Strategies • We were all newbies once • User test your docs!
110. Strategies • We were all newbies once • User test your docs! • Test your docs!
111. Strategies • We were all newbies once • User test your docs! • Test your docs! • Say who you're writing for
112. Strategies • We were all newbies once • User test your docs! • Test your docs! • Say who you're writing for • Different tutorials for different audiences
113. Django for Zope Refugees
114. Intro to Djangoriffic Web Development: Welcome to the Pony Cult!
115. Strategies • We were all newbies once • User test your docs! • Test your docs! • Say who you're writing for • Different tutorials for different audiences
116. Strategies • We were all newbies once • User test your docs! • Test your docs! • Say who you're writing for • Different tutorials for different audiences (or at least file a bug)
117. Thanks! Questions? Karen Rustad karen@ischool.berkeley.edu @mllerustad github.com/aldeka