The Words are Mightier Than the Code.

This talk will focus on technical writing in the Ember community and some ways we can help set new standards for quality. Writing content to help others can also help you level-up and expand your skills.

We'll look at some approaches and patterns and learn to think of our writing as so much more than a blog post or a README.

Transcript

1. The Words are Mightier Than the Code. cball_
2. I do not claim to be a great writer. cball_
3. There will be almost no code in this talk. cball_
4. Think back to when you learned Ember. cball_
5. What are your first questions? How do I use it? Where do I get help? Other resources? What does it do? Who else uses it? cball_
6. What does it do? cball_
7. What are your first questions? How do I use it? Where do I get help? Other resources? What does it do? Who else uses it? cball_
8. How do I use it? cball_
9. How do I use it? cball_
10. How do I use it? cball_
11. What are your first questions? How do I use it? Where do I get help? Other resources? What does it do? Who else uses it? cball_
12. Where do I get help? cball_
13. What are your first questions? How do I use it? Where do I get help? Other resources? What does it do? Who else uses it? cball_
14. Who else uses it? cball_
15. What are your first questions? How do I use it? Where do I get help? Other resources? What does it do? Who else uses it? cball_
16. Other resources? cball_
17. This could maybe use some more resources. cball_
18. Great job Ember website! cball_
19. Wait a second… cball_
20. Writing is a dev's first experience with Ember. cball_
21. How Devs Learn Technical Writing Why spend the time? How to start? Challenges Community Benefits L'agenda cball_
22. How Developers Learn cball_
23. Teach Examples Curated Training Ƅ Screencasts Ɇ Writing Repos Community ſ cball_ How Developers Learn Hack/Slash Inspector
24. Teach Examples Curated Training Ƅ Screencasts Ɇ Writing Repos Community ſ cball_ How Developers Learn Hack/Slash Inspector
25. How Devs Learn Technical Writing Why spend the time? How to start? Challenges L'agenda cball_ Community Benefits
26. How Devs Learn Technical Writing Why spend the time? How to start? Challenges L'agenda cball_ Community Benefits
27. What is Technical Writing? cball_
28. Writing about technical content for a technical audience. cball_
29. Writing about technical content for a technical audience. cball_
30. The first step to writing great content is to know your audience. cball_
31. Technical Writing Examples
32. Tips for writing about cball_
33. Tips for writing about cball_ Use the latest styles /practices.
34. Tips for writing about cball_ If writing for guides or API docs, match style.
35. Tips for writing about cball_ This should not be your addon's README.
36. Good README's should include: cball_ - What the the library does - A link to a demo - Installation instructions - Use instructions - FAQ or gotchas - Supported versions
37. Tips for writing about cball_ Before you start, make sure your knowledge is still current.
38. Complaints around technical writing for Ember. cball_
39. "Online examples are outdated." cball_
40. We can't remove or tag old posts; date is important. cball_
41. If outdated answer, try to add a solution. At least post that it no longer works. cball_
42. How do others know if our content is current? cball_
43. cball_ Version your content!
44. Every blog must date all the things!!! cball_
45. "Ember has a lack of documentation." cball_
46. (just not documentation complete yet) "Ember has a lack of great documentation." cball_
47. Community driven and a very large task. Help out! cball_
48. "Ember is moving too fast. I don't know what these deprecations mean." cball_
49. Ember moved especially fast when heading towards 2.0. cball_
50. Lots of deprecations. cball_
51. We learned a lot from this process. cball_
52. cball_ Things that will improve.
53. cball_ Improved Tooling
54. Effort to document existing deprecations. cball_
55. Deprecations are not Breakprecations. cball_
56. How Devs Learn Technical Writing Why spend the time? How to start? Challenges L'agenda cball_ Community Benefits
57. How Devs Learn Technical Writing Why spend the time? How to start? Challenges L'agenda cball_ Community Benefits
58. Why spend the time? cball_
59. Level up your skills! cball_
60. cball_ Write about topics that you don't understand.
61. cball_ Write about topics that confuse others.
62. cball_
63. The community gets to know you. cball_ photo by @rgbcolor
64. cball_ Even if you don't have rwjblue superpowers.
65. cball_ Become a better writer.
66. cball_ Help others learn Ember the right way.
67. cball_ Let's get best practices and tips out of our heads and into community resources.
68. How Devs Learn Technical Writing Why spend the time? How to start? Challenges L'agenda cball_ Community Benefits
69. How Devs Learn Technical Writing Why spend the time? How to start? Challenges L'agenda cball_ Community Benefits
70. Tips to get started cball_
71. Generate some ideas. cball_
72. Remember ways to Level Up! cball_ Write about topics that you don't understand. Write about topics that confuse others.
73. Look to the guides. cball_ Try to explain things more clearly. Write an article that augments a guide.
74. Create a mindmap. cball_
75. Or an outline. cball_ # Words Mighter Post ## Writing in Ember - Amazing Point 1 - Some tweets ## What - Point 1 - Point 2 ## Why - Point that needs to be first ## Challenges - Point 1 - Point 2 - Point 3
76. <h2> and <ul> it. cball_ <h2>Writing in Ember <ul> <li>Amazing Point <li>Some tweets </ul> <h2>What</h2> <ul> <li>Point 1</li> <li>Point 2</li> </ul> <h2>Why <ul> <li>Point that needs to be </ul>
77. Write like you're talking to someone sitting next to you. cball_
78. Take a day off and re-read before publishing. cball_
79. Add code samples. cball_
80. Write the intro last. cball_
81. How Devs Learn Technical Writing Why spend the time? How to start? Challenges L'agenda cball_ Community Benefits
82. How Devs Learn Technical Writing Why spend the time? How to start? Challenges L'agenda cball_ Community Benefits
83. Challenges cball_
84. Challenge: Keeping it simple. cball_
85. Solution: Revise and practice. cball_
86. Challenge: Getting it technically correct. cball_
87. Solution: 1. Open source - Issues & PRs. 2. Have someone review. 3. ember-community-versions cball_
88. Challenge: Staying up-to-date. cball_
89. Solution: Try to keep your finger on the pulse. cball_
90. Challenge: Finding the time. cball_
91. Solution: Create a schedule. cball_
92. Don't publish weekly; start bi-weekly or monthly. cball_
93. Challenge: Docs w/ features… how do we guide new contributors? cball_
94. Solution: We don't know yet. Maybe automation can help? cball_
95. cball_ Challenge: Improving different skillsets.
96. cball_ Solution: Practice.
97. How Devs Learn Technical Writing Why spend the time? How to start? Challenges L'agenda cball_ Community Benefits
98. How Devs Learn Technical Writing Why spend the time? How to start? Challenges Community Benefits L'agenda cball_
99. Community Benefits cball_
100. A stronger, more-informed community. cball_
101. More resources for newcomers. cball_
102. More audience-specific resources. cball_
103. The Start of a Wave cball_ Ember can help set a new standard for technical writing quality.
104. Prediction: There are many Ember developers that are really good at this. An untapped resource. cball_
105. How Devs Learn Technical Writing Why spend the time? How to start? Challenges L'agenda cball_ Community Benefits
106. How Devs Learn Technical Writing Why spend the time? How to start? Challenges Benefits L'agenda cball_
107. How Devs Learn Technical Writing Why spend the time? How to start? Challenges Benefits Forget half-full, our glass is full-full! cball_ ❤
108. The Words are Mightier. Technical writing allows us to help other developers. cball_
109. It helps us level up. cball_ The Words are Mightier.
110. Allows us to set new standards of quality for something that is usually an afterthought. cball_ The Words are Mightier.
111. Writing is a dev's first experience with Ember. cball_
112. cball_
113. Thanks!