If you have a high-documentation culture, you must have documentation enforcer roles. It's crazy to think you would have a library without librarians to run it.
There must be people who sole role in the company is to spend time on each team (in sequence) trying to follow or review their docs and get X running "like the docs say"
This group of enforcers will contain a variety of people from tech, legal, customer service, and other backgrounds who can spot trash (in their area of expertise) when they see it.
Yeah, having worked at a company who had to publish documentation, the technical writer was definitely an essential role. The engineer can write up the documentation, but you need someone external who can review, and interrogate what is written before it goes out. People are very poor at knowing what they need to communicate.
Unless the documentation enforcer has power, they'll just be an annoying voice. I don't care what that documentation enforcer has to say if my boss prioritizes code over documentation. You'd need management buy-in at every level for a high-documentation culture/company to work.
The same is true for testing though. Lots of shops write as few tests as possible, if any, because the devs don’t have to so they think their way is just fine.
I went from working as the annoying guy asking for tests and docs to the manager and we saw a huge improvement in performance, feature release and a reduction in bugs hitting prod. I can attest their way does not work just fine.
Exactly my thought, these people will burn out and there's just no way around that. Sometimes you need people whose job is to burn out trying to pull others in one direction
Designers to design, draughtspeople to draught, archivists to archive.
Engineering entails a lot of secretarial work that has been "streamlined" by expecting engineers to do it themselves rather than employing professional secretaries to do so. The end result is that it is often left un-done.
The "enforcers" you talk about are basically secretaries, no? Trained individuals with enough understanding of the work at hand to record and file it in a context-aware manner.
Reminds me of the "surgical team" model from The Mythical Man Month [1] wherein there is a suite of people provided to every engineer to minimise their work outside of design and implementation. (At least that's how I remember it, it's a few years since I read it)
I really think this is true, and we usually rely on tech leaders or PMs to do this job, but in reality maybe we should consider having people who are responsible for this full time (or at least part time).
I think having advocates or evangelists within the company is important also, people who can interject "good answer, I think it would be valuable to copy this in a document for the next time someone asks"
There must be people who sole role in the company is to spend time on each team (in sequence) trying to follow or review their docs and get X running "like the docs say"
This group of enforcers will contain a variety of people from tech, legal, customer service, and other backgrounds who can spot trash (in their area of expertise) when they see it.