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_
   
   

   View Slide

2. I do not claim to be
   a great writer.
   cball_
   

   View Slide

3. There will be almost no
   code in this talk.
   cball_
   

   View Slide

4. Think back to when you
   learned Ember.
   cball_
   

   View Slide

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_
   

   View Slide

6. What does it do?
   cball_
   

   View Slide

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_
   

   View Slide

8. How do I use it?
   cball_
   

   View Slide

9. How do I use it?
   cball_
   

   View Slide

10. How do I use it?
    cball_
    

    View Slide

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_
    

    View Slide

12. Where do I get help?
    cball_
    

    View Slide

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_
    

    View Slide

14. Who else uses it?
    cball_
    

    View Slide

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_
    

    View Slide

16. Other resources?
    cball_
    

    View Slide

17. This could maybe use
    some more resources.
    cball_
    

    View Slide

18. Great job Ember website!
    cball_
    
    

    View Slide

19. Wait a second…
    
    cball_
    

    View Slide

20. Writing is a dev's first
    experience with Ember.
    cball_
    

    View Slide

21. How Devs Learn
    Technical Writing
    Why spend the time?
    How to start?
    Challenges
    Community Benefits
    L'agenda
    cball_
    

    View Slide

22. How Developers Learn
    cball_
    

    View Slide

23. Teach Examples Curated
    Training
    Ƅ
    Screencasts
    Ɇ
    Writing
    Repos
    Community
    ſ
    cball_
    How Developers Learn
    Hack/Slash
    Inspector
    

    View Slide

24. Teach Examples Curated
    Training
    Ƅ
    Screencasts
    Ɇ
    Writing
    Repos
    Community
    ſ
    cball_
    How Developers Learn
    Hack/Slash
    Inspector
    

    View Slide

25. How Devs Learn
    Technical Writing
    Why spend the time?
    How to start?
    Challenges
    L'agenda
    cball_
    Community Benefits
    

    View Slide

26. How Devs Learn
    Technical Writing
    Why spend the time?
    How to start?
    Challenges
    L'agenda
    cball_
    Community Benefits
    

    View Slide

27. What is Technical
    Writing?
    cball_
    

    View Slide

28. Writing about technical
    content for a technical
    audience.
    cball_
    

    View Slide

29. Writing about technical
    content for a technical
    audience.
    
    cball_
    

    View Slide

30. The first step to writing
    great content is to know
    your audience.
    cball_
    

    View Slide

31. Technical Writing Examples
    

    View Slide

32. Tips for writing about
    cball_
    

    View Slide

33. Tips for writing about
    cball_
    Use the latest styles /practices.
    

    View Slide

34. Tips for writing about
    cball_
    If writing for guides or API docs, match style.
    

    View Slide

35. Tips for writing about
    cball_
    This should not be your addon's README.
    

    View Slide

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
    

    View Slide

37. Tips for writing about
    cball_
    Before you start, make sure your
    knowledge is still current.
    

    View Slide

38. Complaints around
    technical writing for
    Ember.
    cball_
    

    View Slide

39. "Online examples
    are outdated."
    cball_
    

    View Slide

40. We can't remove or tag old
    posts; date is important.
    cball_
    

    View Slide

41. If outdated answer, try to
    add a solution. At least post
    that it no longer works.
    cball_
    

    View Slide

42. How do others know if our
    content is current?
    cball_
    

    View Slide

43. cball_
    Version your content!
    

    View Slide

44. Every blog must
    date all the things!!!
    cball_
    

    View Slide

45. "Ember has a lack of
    documentation."
    cball_
    

    View Slide

46. (just not documentation complete yet)
    "Ember has a lack of
    great documentation."
    cball_
    

    View Slide

47. Community driven and a very
    large task. Help out!
    cball_
    

    View Slide

48. "Ember is moving too fast. I
    don't know what these
    deprecations mean."
    cball_
    

    View Slide

49. Ember moved especially fast
    when heading towards 2.0.
    cball_
    

    View Slide

50. Lots of deprecations.
    cball_
    

    View Slide

51. We learned a lot from this
    process.
    cball_
    

    View Slide

52. cball_
    Things that will improve.
    

    View Slide

53. cball_
    Improved Tooling
    

    View Slide

54. Effort to document
    existing deprecations.
    cball_
    

    View Slide

55. Deprecations are not
    Breakprecations.
    cball_
    

    View Slide

56. How Devs Learn
    Technical Writing
    Why spend the time?
    How to start?
    Challenges
    L'agenda
    cball_
    Community Benefits
    

    View Slide

57. How Devs Learn
    Technical Writing
    Why spend the time?
    How to start?
    Challenges
    L'agenda
    cball_
    Community Benefits
    

    View Slide

58. Why spend the time?
    cball_
    

    View Slide

59. Level up your skills!
    cball_
    

    View Slide

60. cball_
    Write about topics that
    you don't understand.
    

    View Slide

61. cball_
    Write about topics that
    confuse others.
    

    View Slide

62. cball_
    

    View Slide

63. The community gets
    to know you.
    cball_
    photo by @rgbcolor
    

    View Slide

64. cball_
    Even if you don't have
    rwjblue superpowers.
    

    View Slide

65. cball_
    Become a better writer.
    

    View Slide

66. cball_
    Help others learn Ember
    the right way.
    

    View Slide

67. cball_
    Let's get best practices and
    tips out of our heads and into
    community resources.
    

    View Slide

68. How Devs Learn
    Technical Writing
    Why spend the time?
    How to start?
    Challenges
    L'agenda
    cball_
    Community Benefits
    

    View Slide

69. How Devs Learn
    Technical Writing
    Why spend the time?
    How to start?
    Challenges
    L'agenda
    cball_
    Community Benefits
    

    View Slide

70. Tips to get started
    cball_
    

    View Slide

71. Generate some ideas.
    cball_
    

    View Slide

72. Remember ways to Level Up!
    cball_
    Write about topics that
    you don't understand.
    Write about topics that
    confuse others.
    

    View Slide

73. Look to the guides.
    cball_
    Try to explain things
    more clearly.
    Write an article that
    augments a guide.
    

    View Slide

74. Create a mindmap.
    cball_
    

    View Slide

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
    

    View Slide

76. and it.
    cball_
    Writing in Ember
    
    Amazing Point
    Some tweets
    
    What
    
    Point 1
    Point 2
    
    Why
    
    Point that needs to be
    
    

    View Slide

77. Write like you're talking to
    someone sitting next to you.
    cball_
    

    View Slide

78. Take a day off and re-read
    before publishing.
    cball_
    

    View Slide

79. Add code samples.
    cball_
    

    View Slide

80. Write the intro last.
    cball_
    

    View Slide

81. How Devs Learn
    Technical Writing
    Why spend the time?
    How to start?
    Challenges
    L'agenda
    cball_
    Community Benefits
    

    View Slide

82. How Devs Learn
    Technical Writing
    Why spend the time?
    How to start?
    Challenges
    L'agenda
    cball_
    Community Benefits
    

    View Slide

83. Challenges
    cball_
    

    View Slide

84. Challenge:
    Keeping it simple.
    cball_
    

    View Slide

85. Solution:
    Revise and practice.
    cball_
    

    View Slide

86. Challenge:
    Getting it technically correct.
    cball_
    

    View Slide

87. Solution:
    1. Open source - Issues & PRs.
    2. Have someone review.
    3. ember-community-versions
    cball_
    

    View Slide

88. Challenge:
    Staying up-to-date.
    cball_
    

    View Slide

89. Solution:
    Try to keep your finger
    on the pulse.
    cball_
    

    View Slide

90. Challenge:
    Finding the time.
    cball_
    

    View Slide

91. Solution:
    Create a schedule.
    cball_
    

    View Slide

92. Don't publish weekly;
    start bi-weekly or monthly.
    cball_
    

    View Slide

93. Challenge:
    Docs w/ features… how do we
    guide new contributors?
    cball_
    

    View Slide

94. Solution:
    We don't know yet. Maybe
    automation can help?
    cball_
    

    View Slide

95. cball_
    Challenge:
    Improving different skillsets.
    

    View Slide

96. cball_
    Solution:
    Practice.
    

    View Slide

97. How Devs Learn
    Technical Writing
    Why spend the time?
    How to start?
    Challenges
    L'agenda
    cball_
    Community Benefits
    

    View Slide

98. How Devs Learn
    Technical Writing
    Why spend the time?
    How to start?
    Challenges
    Community Benefits
    L'agenda
    cball_
    

    View Slide

99. Community Benefits
    cball_
    

    View Slide

100. A stronger, more-informed
     community.
     cball_
     

     View Slide

101. More resources for
     newcomers.
     cball_
     

     View Slide

102. More audience-specific
     resources.
     cball_
     

     View Slide

103. The Start of a Wave
     cball_
     Ember can help set a new
     standard for technical writing
     quality.
     

     View Slide

104. Prediction:
     There are many Ember developers that
     are really good at this.
     An untapped resource.
     cball_
     

     View Slide

105. How Devs Learn
     Technical Writing
     Why spend the time?
     How to start?
     Challenges
     L'agenda
     cball_
     Community Benefits
     

     View Slide

106. How Devs Learn
     Technical Writing
     Why spend the time?
     How to start?
     Challenges
     Benefits
     L'agenda
     cball_
     

     View Slide

107. How Devs Learn
     Technical Writing
     Why spend the time?
     How to start?
     Challenges
     Benefits
     Forget half-full, our glass is full-full!
     cball_
     ❤
     

     View Slide

108. The Words are Mightier.
     Technical writing allows us to
     help other developers.
     cball_
     

     View Slide

109. It helps us level up.
     cball_
     The Words are Mightier.
     

     View Slide

110. Allows us to set new standards of
     quality for something that is usually an
     afterthought.
     cball_
     The Words are Mightier.
     

     View Slide

111. Writing is a dev's first
     experience with Ember.
     cball_
     

     View Slide

112. cball_
     

     View Slide

113. Thanks!
     

     View Slide