|
The sad truth is that it's the average README that's hilariously bad, not that you did something strange or wrong. As you say - whenever something is trying to be useful to anyone other than the author, the author should in turn try to be helpful. Unfortunately, programmers always had a love-hate relationship with documentation (love it when you need it and others wrote it for you, hate the guts of it if it's you who need to write it), but I think it got progressively worse in the last decade. At work, I have to often seriously fight for there to even be a README. Lack of docs and docstrings, lack of meaningful comments in the code, utter lack of visualization was the norm in the 90s, then it got better for a while, and now we've done a full circle and are back with undocumented spaghetti everywhere. It's really strange, and I don't understand why it's like this. I tell people who nominally are way past being juniors to read their code before making a PR - to see how easy to understand it is - and they look like they just got enlightened. Like, isn't this (reading your own code) the most basic of all ways of working with code? Same for READMEs, I tell them to put all the information needed for a new person to set the project up, and am met with blank stares - why would they, programmers, bother with writing down plain English and managing the information surrounding what they do? Have these guys never thought about what the "I" in "IT" means? Sorry, that's a possibly unwarranted rant, but when I see posts like GP's that seem to assume that writing a helpful README is somehow strange and a waste of effort unless it translates into clicks, it just blows my mind, it a pretty negative way. |
you're not alone my dude. i have a similar challenge w/ my engineers. my best lead is an artisan and its proud of what he authors, and like me sees their code as part of the product UX / funnel (1%). the others (99%) i have to get a bit draconian or simply create company templates they must adhere to or PRs get rejected and they hear from me on their 1:1s.
you either love it or you don't. and if you don't, follow the rules like a big boy or get called out.
ultimately you have to set a culture for it even if it is pulling teeth because you net net it impacts the PnL.