Merry Christmas and Happy Holidays. Peace. Best of health wishes to you and your loved ones in 2022.
Are you dev doc readers asking what’s up with some of your docs? It’s a blocker for many teams. Good ones are building grid containers for content. Long docs are so 1999. Especially when your users want easy-to-read 5 minute docs. One solution is to containerize your docs. The best solution. At least in structure. Think short paragraphs in boxes. It’s a simple way to help users consume technical values and concepts in small sections. Long form API docs waste user time. Short works better. Small sets of information let users sift rather than read long paragraphs.
See for yourself…
- Stripe
- Epic Games (one of mine)
- Worldpay
- WSO2
UI/UX
Color contrast helps doc users reduce eye strain. GitHub does it well. WorldPay too. Deep blue works for Stripe. Giving users the option to choose their contrast preference is smart. Devs working long hours will thank you for eye rest from white.
Doc Templates
Build templates for doc formats and diagrams. They cut out confusion when 5 different writers each have their personal styles. Not ideal for API docs. Good API doc writers use a writing style guide to unify language. No predicting or historical references to 3 steps back.
Writing style guide
Need one? Here’s two, free:
- Google dev writing style guide (my preference)
- Microsoft writing style guide (casual city)
- Bonus: tech writer checklist
Screenshots
Big screenshots are tough. Users don’t know exactly where to look. Animated GIFs solve wandering eyes. Here’s one I built how to sign up for the AWS CloudTrail. It took 2 minutes to film, then convert the MP4 file to GIF here. Do users really want a grainy screenshot? No.
Drop me a note. I’ll reply.