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.
Video
- 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!
- New devs aren't familiar with code conventions
- Developer environments are hard
- New devs lack context
- 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