I’ve being thinking about about this for quite sometime now, how should one go about documenting a rails app in a higher level than code documentation ?
And I’m currently facing the exactly issue that first sparked that though in me, that is trying to find if there’s already some code on that app that does what I need to do.
Some context, I have started a new job on the past 3 weeks and I’m working on maintaining a relatively big app and I need to import some CSV data for a new client, looking through the code I found about 2 CSV importer classes with absolutely now documentation, I don’t know which one to use at all, which are they use cases (or even if they have the same use case and some dude just made the other because he didn’t know of the previous one?)
Another example, working on a way bigger app (almost 5x times bigger, based only on LOCs), I found out some JS duplication and extracted to a helpful class that would be useful on a lot of places, but how should I document it? Just adding comments wouldn’t help my teammates know that this code exists and that they should use it when they need to. Reading the commits help but having to keep all that ‘context’ is a burden.