[pmx]

> In one example I came in and found a data vault project that wasn’t being used. It actually had pretty good documentation. However, the team had taken so long and hadn’t fully completed the project which led to their dismissal.

I feel like this is a major reason things don't get documentation. We don't get judged on it, nobody cares how good the docs are, but they DO care that we're shipping features.

[cmiles74]

The most praise I've ever received for my documentation was from the developers forced to read it after I moved on to a position with another company. It's a little unfortunate I didn't hear more about it as I was writing it, but then again it's the kind of stuff other developers find useful.

Still, in my opinion, spending the time writing documentation was a net positive: it didn't take me all that long to write up and it clearly made someone else's job easier, so much so that they mentioned it to me. And, of course, I've had to read my own docs more than once.

[yourapostasy]

> It's a little unfortunate I didn't hear more about it as I was writing it...

This is usually because most people find it faster and easier to ping the random access memory that is you while you are there instead of serially reading the documentation. I have found a non-linear correlation going in the wrong direction between the comprehensiveness of the documentation written, and the amount of requests for live assistance on the very matters covered in the documentation, when the requestee is the author of the documentation.

This is where an effectively-segmented Table Of Contents comes in handy. As the author, instead of rewarding unwanted organizational behavior by giving the requestor the spoon-fed answer they seek even if the requestee knows it off the top of their head, encourage the organization a "teach them to fish" posture by pointing them in the right direction by the chapter section.

"It will be somewhere in Chapter Foo" gets the requestors to familiarize themselves with the documentation structure at least in piecemeal fashion.

Junior engineers who make a habit of asking questions already addressed in documentation and don't take the "LMGTFY"-type responses as a hint they should search first, ask later, I start helping by asking, "what keywords did you try searching upon in the documentation", and start a conversation about why they used only such keywords. I'm excited by the RAG-family generative AI I am able to start loading documentation into that will let me ask, "what prompts did you try upon the documentation fine-tuned AI", as these AI's are powerfully effective with functionally fuzzy keyword searches. I'll fine-tune the documentation when it looks like various terminology is used over and over by searchers, but in general this approach works great to teach juniors how to search for information.

Engineers who don't quickly learn and keep asking for spoon-fed answers, enter an endless loop where they might occasionally help fine-tune the documentation, but otherwise are only pointed to the general area to search, and delegated to their colleagues who have learned to search for peer-led instruction. In over 20 years of applying this strategy, I've yet to run into an engineer who would not eventually learn, though if I did, they probably self select out of this field.

In a dog fooding fashion, when I ask someone for help, after my specific ask of them, I tell them what documentation I tried availing myself of first, what terms I searched upon, how I reasoned through to the point where I'm stuck, and what my theories/models are of what I think is happening. This helps rapidly prune the tree of responses, and 80% of the time the response is along the lines of, "oh, yeah the official documentation is out of date, use this technical note instead".

[devjab]

Should they care? I’ve come into organisations that had spent entire years worth of man hours on setting things up correctly so that they could potentially scale to millions of concurrent users. Organisations which would never reach more than 50.000 concurrent users in their wildest dreams.

On the flip side I’ve seen some extreme cowboy hacker man code run perfectly fine for its entire 10 year life cycles.

Now, I don’t think you should go completely cowboy, but I do think you should think about whether or not your “correctness” is getting in the way of your actual job. Which is typically as a service function where you’re supposed to deliver business value at a rapid pace. Obviously it depends on what you do. If you work in medical software you’re probably going to want to get things right, but just how much programming could be perfectly fine if it was just thrown together without any adherence to “correctness”? The theory tells you it’ll cost you down the line, and in some cases it will. In my anecdotal experience it’s not as often as we might like to think, and sometimes the cost is even worth it. In two decades I’ve only ever really seen two poorly build systems cost so much down the line that they would’ve been better off having been build better from the get go. In both cases they couldn’t have been build better upfront because the startups didn’t have the people to do so.

[g4zj]

I think I write decent documentation, but my target audience is usually my future self. If I can rely on my own documentation to help quickly reacquaint myself with the project later on, I generally consider it sufficient.