Hello colleague, thank you for your post. I was about to write something similar, as i see the discussion (again) talks about technical topics and things that might happen in the future.
While (imho) we need to write down a list of problems the documentation system should address and then find a method to put information into or near code with low or zero overhead for the person writing it.