DevRel Scribbles
  • What are Scribbles?
  • Index
  • Developer Advocacy
  • Developer Advocates
  • Life as a developer advocate
  • Modernising Red Hat’s enterprise developer program
  • Engaging 9-year-old software developers
  • Making 22-year-olds love 26-year-old software
  • Dogfooding developer products: gathering insights from internal hackathons
  • How far does your ethical responsibility stretch for the tech your devs create?
  • Outside the lecture theatre
  • How do you design programs for diversity?
  • Build the Platform Your Developers Actually Want
  • Measuring dev rel programs far beyond marketing activities
  • Developer Evangelism
    • Developer Evangelists
    • How to rock a technical keynote
    • The Art of Slide Design
    • The Art of Talk Design
    • The Art of Story Design
    • Dev events beyond 2021
  • Developer Experience
    • The Power of Content
    • Building a Developer Community in an Enterprise World
    • How to lose a dev in three ways
    • Developer relations, why is it needed?
    • The hierarchy of developer needs
    • GitHub is your documentation landing page
    • Docs as engineering
    • Commit messages vs. release notes
    • A11y pal(ly)- crafting universally good docs
    • Inspiring and empowering users to become great writers, and why that’s important
    • Solving internal technical documentation at Spotify
  • Community Management
    • Building community flywheels
    • DevRel = Community Management?
    • Creating high-quality communities
    • How to grow a healthy Open-Source community?
    • Managing communities at scale
    • Using community to drive growth
    • Useful community success metrics
    • Communities aren't funnels
    • How to mobilise your community during a pandemic
  • Managing a DevRel Team
    • Developer Relations + Product
    • Distributed developer relations
    • Understanding company goals
    • DevRel Qualified Leads (DQL)
    • Path to success for DevRel
    • How to move up in your organization
    • Four pillars of DevRel
    • Building your DevRel dream team
    • Managing the burnout burn-down
    • I messed up and I’m going to get fired
    • How to report on community relationships without being creepy about it
    • How to scale a developer relations team
  • Misc
    • Is developer relations right for you?
    • Tooling your way to a great DevRel Team
    • Planning your DevRel career
    • Success metrics as narratives
    • Get executive buy-in or else
    • Introduction to the AAARRRP devrel strategy framework
    • Strategy for developer outreach
    • Connecting dev rel and product
    • Performance DevRel
    • Ultimate cheat codes for healthier travel
Powered by GitBook
On this page
  • Summary
  • Create Inclusive documentation
  • 3 ways to lose a dev due to documentation
  • How to fix this?
  • Scribbles
  • Edge cases for great product documentation:
  • Three ways you might lose new developers due to your documentation
  • What you can do to fix this tomorrow?

Was this helpful?

Export as PDF
  1. Developer Experience

How to lose a dev in three ways

Jamie Wittenberg talks about great ways you can incorporate to make your documentation better and more accessible to new developers.

PreviousBuilding a Developer Community in an Enterprise WorldNextDeveloper relations, why is it needed?

Last updated 3 years ago

Was this helpful?

Summary

Create Inclusive documentation

  • It is the right thing to do for developers but also for the business

  • The documentation is someone's first experience with your product

  • Your documentation is the best marketing material you might have!

3 ways to lose a dev due to documentation

  • New devs aren't familiar with code conventions

  • Developer environments are hard

  • New devs lack context

How to fix this?

  • Test your docs on different operating systems and have someone with low development experience try it

  • Create a legend & glossary for your documentation

  • Add context to your tutorials

Scribbles

Edge cases for great product documentation:

  • Users should be able to simulate the development environment

  • Users should not be entering their personal information, email addresses or use any credit cards for accessing the documentation

  • Users should be able to save their work and return to it.

  • Assume that users might not have written a single line of code before

  • Users should be able to access everything with even tablets or cell phones

Three ways you might lose new developers due to your documentation

New developers are not familiar with code conventions

  • Problem:

    • $ sudo apt update - Newbies might not understand what a simple $ here might represent

      • Similarly,

        • Using >>> for interactive shell

        • Using [ ] around values where you want people to substitute their API credentials

      • You cannot avoid conventions generally because they increase inclusivity generally

  • Solution

    • Include a legend in your documentation that defines any conventions used.

  • Problem:

    • New developers aren't familiar with developer workflows, such as when to use the command line vs a text editor.

      • Eg: Newbies might get confused what part of documentation represents shellcode and what represents javascript code.

  • Solution

    • Use visual differentiation to indicate different parts of the developer workflow

      • Use syntax formatting, number lines, etc,

      • Different parts to indicate output vs input files, code vs shell etc.

  • Problem:

    • Even with the best explanations, some of the things might get lost.

  • Solution

    • Use screencast or gifs to make developers aware of the process.

Developer Environments are hard

  • Don't assume the operating system one might be using for accessing your code.

    • Eg.: A lot of documentation assume people using UNIX/ Linux systems and Windows users might get discluded.

  • Solution 1

    • Link to someone else's explanation of how to use different operating systems.

    • Write your own detailed solution for these specific cases: More involved and yields greater benefits by keeping developer on your platform

  • Solution 2

    • Explain command and environmental differences, using a different platform, shells and respective commands for that

  • Solution 3

    • Set up examples on Codepen, Glitch or repl.it, where they can run and test your documented example code.

  • Solution 4

    • If a browser-based development environment does not work for your product, use a VPS/ VM solution for that.

New devs lack context

  • New Developers don't know what your product does

    • Solution: Add a few sentences at the beginning of the quickstart and tutorials. Include key activities.

  • Your docs are expansive and hard for a new dev to navigate

    • Solution: Provide use cases for your product and use them to guide developers through your documentation

  • Your docs are hard to find or your product requires signing up to test

    • Solution: Create a sandbox

What you can do to fix this tomorrow?

  • Have a friend with less development experience try one of your tutorials and document every confusing point

  • Test your docs on different operating systems

  • Create a legend for your documentation

  • Add a glossary to your documentation

  • Add context to your tutorials

Video