4 ms·
First and foremost, I really appreciate the project, so thank you for your help with it! Documentation is honestly probably one of, if not the most difficult p
by jonwest 3y ago
First and foremost, I really appreciate the project, so thank you for your help with it!
Documentation is honestly probably one of, if not the most difficult part of development. Even if the programming problem you’re solving is immensely difficult, how do you then simplify that in such a way that it is accessible to a wide range of backgrounds? I’ve heard that writing code is hard, but reading code is harder—and documentation is essentially writing about reading code, so I wouldn’t beat yourself up about it.
The merge feature is immensely helpful, and I’ve found that writing internally focused documentation really does help with adoption. As in, “here at XYZ we are using this tool in these cases—here is how and when you would use each of them. Here’s a link to more contextual documentation”. Even if people don’t actively seek out the documentation, it’s still a hell of a time saver to point the tenth person asking how or why to do something to a static copy of what would essentially be the response.
- ithkuil 3y agoDocumenting some code you wrote is hard because you have to forget you everything about it (all the thought processes that led you to the point of writing that piece of code, with that design, etc) and put yourself in the shoes of an arbitrary end user. To make things more complicated there are many different users coming from different backgrounds and having different sets of thins that are obvious or non-obvious to them