There needs to be a process and probably at least a librarian and even then it's often not obvious. In my experience, a lot of written material gets into the "not quite right any longer but we don't have anything better"--and if you go to update it there's invariably a lot of things that end up getting changed. Not sure I've ever cracked open an old paper or blog post and just changed one thing.
bringing it to a normal contrast again requires a review of the documentation and some kind of punishing if someone just clicks "yeah, it is still fine".
I hate outdated documentation, primarily including mine.
Some datestamp next to multiple areas with a "last reviewed/approved on" info would likely be useful, esp if someone could flag items that are known out of date/wrong/broken for review, even if they didn't know what 'correct' was. I've hit this multiple times as a new person on a team/project - at least those that had moderate documentation. I know "example A" doesn't work, but I don't yet know why it's wrong or how to fix it, but flagging it for review would help me not lose track of it.
This was just an (extreme) example - what I meant is a way to make the users of the documentation pissed off enough so that they react, which in turn forces the author of the doc to update it.
There were even cases of printing off doc pages, writing on them while in the field, and updating the digital version.
And it meant that we operated with “one brain” where the documentation always represented the most current collective knowledge.
It was awesomely effective
My last place did a fantastic job in documentation. The culture was established before I was there, and I did bring in the diataxis framework to focus the types of documentation we wrote, but engineers had a good set of documentation to start.
It wasn't all rainbows, but many slack conversations were "I wrote this a few months back - let me know what questions you have."
The basic assumption is that most developers don't hate writing documentation other than they don't feel like they do it well and don't feel like it's effective. The best way to make it feel effective is threefold - build a proper framework on which you can attach the documentation for discoverability; build an expectation for a documentation portfolio; and build it into your definition of done at the feature level;.
1. Build a proper framework. Techdocs is part of backstage and uses your own git repository to build it in markdown. https://backstage.io/docs/features/techdocs/techdocs-overvie... has more information. Diataxis is a good start to how to think about the types of documentation. https://diataxis.fr/ is what I use to separate out the types of documentation that need to be written. Most documentation in my experience is written as "explanation." Having API reference and howtos are important, and so many howtos are just built out of asking someone on slack anyway.
It is a matter of saying, "you've already done the work to discover this: just put a rough draft where I've put it to be and people can refine it as they go."
2. Build an expectation of a documentation portfolio. I write about that at https://www.ebiester.com/documentation/2020/06/02/agile-docu... but it was a concept written about in Agile Documentation. Start with "these are the minimum requirements for a new project" and keep it very light. Build documentation, codebase expectations, and a quick architectural tour is likely enough to start and the rest will follow.
3. Build it into the definition of done. This takes management buyin, but it means taking it into account for the schedule as technical debt originally. It will not slow you down in the end, but the activation energy of learning takes some time. But just like unit tests or manual testing, there's a set of expectations that are baked into calling something done.
I think a bonus is that so much of documentation is built through our chat and email programs, and just having the courage to copy it out and clean it up a little or take videos and transcripts of debugging sessions is a good start, but it's easy to make a mess. The key is categorization.
At the best companies that I've worked for, the ration was in the 1-10 to 1-5 range, and the salaries were close.
That part.
Typed, properly named code doesn't need 'docs' per se. Documented code like:
// Sender public key
const spk;
// Send tokens
function txV(){ .. }
const sender: PublicKey
function sendTokens(){ .. }
Those were being maintained in the wiki.