The Words are Mightier Than the Code.

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.

6254dc2b7e4f26b2ab5d05c560834671?s=128

Chris Ball

August 27, 2015
Tweet

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!