4 ms·

> Very few non-marketing technical writers make it these days without being competent in git. At least in the software industry, agreed. Not only is it reasona

> Very few non-marketing technical writers make it these days without being competent in git. At least in the software industry, agreed. Not only is it reasonable to expect a TW at an dev-heavy org to familiarize themselves with devs' tools, but it's also damn near impossible to find a good tool for software docs unless you're running your own static site generator. Every premium CMS tool on the market has some kind of dealbreaking fatal flaw... among them their average price, because good luck getting any budget for documentation :P

MilStdJunkie 3y ago
Introducing Asciidoc to a aerospace team, I was lucky if anyone in the room even knew what git was, let alone how to use it. Every publication system carries with it the paradigm of the industry it's born from, and so-called "docs-as-code" is no different. I still believe that Asciidoc+Version Control+Build Engine of Choice is absolutely the way to pump out complex documentation, but my belief in that fact is probably shaped by the fact I'm at least half programmer myself. When you have an org that doesn't know what merges do, and who absolutely, positively will not review a draft that's not dead tree, the "docs-as-code" approach runs into some real speedbumps, because you have to get all that SME crayon scribble back into the system somehow. It's honestly a problem I still haven't solved yet, in spite of multiple years of effort, to my shame. I just can't see how reviewing a PR is hard, exactly. Like, what part? The part where you see the changes? I dunno. Of course your big ERP vendors will have all the answers here, which is always "Use More Brand X ERP". The secret move is that ERPs come with VP level - and above!! - backing, unlike your Publication System Initiative, which has the backing of maybe a second-tier manager, some PMs, and some burnt out CMS admins.

MilStdJunkie 3y ago

Introducing Asciidoc to a aerospace team, I was lucky if anyone in the room even knew what git was, let alone how to use it. Every publication system carries with it the paradigm of the industry it's born from, and so-called "docs-as-code" is no different. I still believe that Asciidoc+Version Control+Build Engine of Choice is absolutely the way to pump out complex documentation, but my belief in that fact is probably shaped by the fact I'm at least half programmer myself. When you have an org that doesn't know what merges do, and who absolutely, positively will not review a draft that's not dead tree, the "docs-as-code" approach runs into some real speedbumps, because you have to get all that SME crayon scribble back into the system somehow. It's honestly a problem I still haven't solved yet, in spite of multiple years of effort, to my shame. I just can't see how reviewing a PR is hard, exactly. Like, what part? The part where you see the changes? I dunno. Of course your big ERP vendors will have all the answers here, which is always "Use More Brand X ERP". The secret move is that ERPs come with VP level - and above!! - backing, unlike your Publication System Initiative, which has the backing of maybe a second-tier manager, some PMs, and some burnt out CMS admins.