"The last bullet is the most frequently omitted from definitions of docs as code, but I would say that it's the most important." — I agree that this is often very important, but docs as code has strong benefits even where the process does not involve software developers *at all*.
That's because a docs as code toolchain can make documentation *much* easier to track, review, maintain and deploy than is often the case with more traditional approaches. This means that technical writers can publish specific updates and fixes to documentation faster, with better traceability.
That's all extremely beneficial to any organisation, not just those that revolve around software developers.
I agree there are benefits for technical writers and others, especially automated builds and tracking changes in Jira. I'd add that those things aren't exclusive to Docs as code (See: https://askmeaboutapis.com/topics/toolchain-types_2.html ).
Docs as Code evolved out of the specific need to get engineers to write more documentation, so it tends to be the ideal solution where engineers are doing the bulk of the writing.(The companies that made the first presentations about it at Write The Docs were Google and Twitter.)
That said, whatever toolchain you use should be making life a lot easier for your authors as well as your customers. (See https://askmeaboutapis.substack.com/p/when-docs-as-code-is-a-big-success) If your engineers don't contribute to docs at all, the automated builds are still good but storing source files in the same repo as the code is very likely to become an unnecessary hassle. Plan your implementation carefully.
I understand that you're not knocking it; I was just responding to the underlying assumption in your point about the statement that is usually missing but "the most important". Your point has merit when software development is the main business at hand (your underlying assumption) — but is irrelevant when it is not.
Yes, docs as code originated in the software development context and, to date, is little-known outside of that context. But docs as code is not inherently tied to software development as your underlying assumption implies. This could be why "The last bullet is the most frequently omitted from definitions of docs as code".
In response to "If your engineers don't contribute to docs at all, the automated builds are still good but storing source files in the same repo as the code is very likely to become an unnecessary hassle.": Given what I've just said, there may not even *be* any software code, only documentation code. I believe that a docs as code approach can be advantageous *outside* of the software development context too.
However, I do concede that, given the current state of docs as code options, it is much harder to get buy-in and to implement docs as code tools and processes outside of the software context. I'd like to see things mature so that, for example, we can present reviewers with a docs-focused interface that feels somewhat familiar to the average user, rather than a software-focused pull request that is familiar only to coders (and intimidating to most others).
Thanks for the links, I've bookmarked those to read soon.
"The last bullet is the most frequently omitted from definitions of docs as code, but I would say that it's the most important." — I agree that this is often very important, but docs as code has strong benefits even where the process does not involve software developers *at all*.
That's because a docs as code toolchain can make documentation *much* easier to track, review, maintain and deploy than is often the case with more traditional approaches. This means that technical writers can publish specific updates and fixes to documentation faster, with better traceability.
That's all extremely beneficial to any organisation, not just those that revolve around software developers.
I'm not knocking Docs as Code, Eric. I like it.
I agree there are benefits for technical writers and others, especially automated builds and tracking changes in Jira. I'd add that those things aren't exclusive to Docs as code (See: https://askmeaboutapis.com/topics/toolchain-types_2.html ).
Docs as Code evolved out of the specific need to get engineers to write more documentation, so it tends to be the ideal solution where engineers are doing the bulk of the writing.(The companies that made the first presentations about it at Write The Docs were Google and Twitter.)
That said, whatever toolchain you use should be making life a lot easier for your authors as well as your customers. (See https://askmeaboutapis.substack.com/p/when-docs-as-code-is-a-big-success) If your engineers don't contribute to docs at all, the automated builds are still good but storing source files in the same repo as the code is very likely to become an unnecessary hassle. Plan your implementation carefully.
Hi Clarence, thanks for your reply.
I understand that you're not knocking it; I was just responding to the underlying assumption in your point about the statement that is usually missing but "the most important". Your point has merit when software development is the main business at hand (your underlying assumption) — but is irrelevant when it is not.
Yes, docs as code originated in the software development context and, to date, is little-known outside of that context. But docs as code is not inherently tied to software development as your underlying assumption implies. This could be why "The last bullet is the most frequently omitted from definitions of docs as code".
In response to "If your engineers don't contribute to docs at all, the automated builds are still good but storing source files in the same repo as the code is very likely to become an unnecessary hassle.": Given what I've just said, there may not even *be* any software code, only documentation code. I believe that a docs as code approach can be advantageous *outside* of the software development context too.
However, I do concede that, given the current state of docs as code options, it is much harder to get buy-in and to implement docs as code tools and processes outside of the software context. I'd like to see things mature so that, for example, we can present reviewers with a docs-focused interface that feels somewhat familiar to the average user, rather than a software-focused pull request that is familiar only to coders (and intimidating to most others).
Thanks for the links, I've bookmarked those to read soon.