4 ms·
I wrote a whole Twitter thread a while back on this very topic: https://twitter.com/alexpotato/status/1224309861304938496 https://twitter.com/alexpotato/status/
by alexpotato 6y ago
I wrote a whole Twitter thread a while back on this very topic: https://twitter.com/alexpotato/status/1224309861304938496 https://twitter.com/alexpotato/status/1224309861304938496
The single biggest ROI I've seen on getting documentation written is to provide a template for developers to fill out.
Blank wiki pages are incredibly intimidating and developers can't always anticipate what people will want. Having a "madlib" style outline with things like:
- Where does this app run?
- How do you start it?
- Where are the logs?
- How do you common items X,Y,Z?
Takes your odds of documentation being written from near zero (in my experience) to at least 60%.
- akudha 6y agoMy manager uses a template to create JIRA tasks - it makes it short and to the point. Just a handful of questions like Who needs it? what needs to be done? who is the subject matter expert? and so on. This makes it easier for the developer working on the task, keeps the description short and sweet.
- alexpotato 6y agoA past manager of mine used to do the same thing but using templates for PRs (which is a great GitHub feature)
- nobodyandproud 6y agoThanks. This is a great idea.
- 908B64B197 6y agoThis. Some of the best documentation is a simple "getting started" guide that explains: How to build (any dependencies?), how to hook a debugger or access debug logs and some pointers to where to start when looking at code (example: set a breakpoint here and trigger this action, you'll end-up in X component and should be able to figure out what's going on from there).