Hacker News new | past | comments | ask | show | jobs | submit login

Tools are great, but here's the million-dollar question: how do you make people maintain the docs?



I actually have an approach here: ASCII diagrams, so i can embed them in code or a README.

It keeps things simple - you can't have a super complex ASCII diagram; even crossing lines look terrible - and there's at least a fighting chance that when someone changes the code they will at least notice the diagram is out of date.

To prevent insanity, I use a tool to help draw them: Monodraw in my case.


Another question: how do you make people maintain quality docs? Sometimes I start to doubt, if it's even possible to maintain some order with bigger solutions, because even if you can force yourself to document well everything, there will be always people that either don't know solution well enough, they don't know how to prepare good documentation or they don't want to bother with it.


We have a few ideas in that area revolving around our Slackbot, keep watching for our next releases for more details.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: