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.

Summary

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

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

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.

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 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

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

Last updated 2 years ago