$30 off During Our Annual Pro Sale. View Details »

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.

Chris Ball

August 27, 2015
Tweet

More Decks by Chris Ball

Other Decks in Programming

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