|
I mean this rather straight, not cynically: I consider the request for "more documentation" to be a political ploy from people who don't want to do whatever it is you're trying to do, and "it needs more documentation" is a dirt-cheap stopper they can throw at you because in their (correct) experience people tend not to document things. They may not mean it as such a ploy, but it is what it is. So I go ahead and document things anyhow. I sort of naturally fall into documentation-first development, so I almost always have it. And what I've found is, this doesn't make people read your documentation. What it does is it makes people stop asking for it. Hence my belief about it being a ploy more than anything else, again, perhaps not consciously, but in effect. When people do read documentation, I find people do a very surface read of it. You can say "This JSON object has these three parameters, 'age' which must be an int, 'name' which must be a string, and 'status' which must either be a string from one of these three values or be entirely missing", provide them a JSON schema or some other standard format that precisely specifies that and can be automatically used to validate and/or generate code, and you'll get things submitted to your API that more or less have an age, a name, and a status, but sometimes the age will be a string with a number in it, the name attribute will experience various capitalizations of the attribute name (not the value), and they'll push status as an empty string and then complain when your API rejects it. I often find myself a bit agog at my fellow programmers with decades of experience who still seem to be struggling with the concept that I can't write code that takes "stuff" any more than they can and are so careless about interacting with an API or something, and then get pissy when the code fails because of unexpected input. I'm not angry about this, either... because I've learned to just budget the time for it and 100% expect it as part of the process. I fully expect to be asked for documentation, for them to do a surface read of it, and for us to have to work through the process of actually conforming to the documentation. I will send them references to the docs as we go but I scrupulously avoid even a hint of the idea that they should have already known this because I documented; it is only references to convenient examples I happen to have on hand, or whatever other softening I can apply. And of course, I am not perfect either, and when I do edit the documentation because of something I hadn't considered, I always make a point of calling out that the documentation wasn't quite correct and I've fixed it, so it doesn't look like an accusation. It's just part of the process. |
I can't say it always stops people for asking them. Even when they've commented on the documentation when it was shared, even when the conversation started around a link to the documentation, I've found people one month in when it's time for them to do something ask for documentation with the implication there is none, and if you provide it in the meeting where they're trying to prolong the process they just insist they need time to review it despite having had at some stages a month to do so (or having left comments that at least indicate they already did)