Docs as Code - What is documentation?

[lief-erickson]

Second, “everything in code” means put the docs in the product codebase -- not in a database, not in a separate repository. This excludes most conventional wiki and web-based CMS platforms, as they depend on relational databases that hide the source behind a tool that is wholly inadequate for source and version control. We'll discuss integrating your documentation source and platform into the repo and the product itself. This is addressed in <>.

.DocOps -- General Concept image::diagram-docops-general.png[]

Is the term "documentation" defined somewhere? I don't recall reading a definition up to this point. I know the definition can be a bit slippery, but if we want to think of docs-as-code, then we not think documentation means lots and lots of words. Most people when they think of "documentation" think long-form content. The diagram-docops-general.png image infers it's more, but the text so far in this book seems to always mean long-form content. If that view is maintained, then it's harder for tech writers to get their hands on the UI strings.

UI strings are documentation (or are at least often used in the documentation). UI strings should be maintained in a separate file (if for no other reason than for localization of the UI) that can be pulled into/sourced by the documentation so that when the UI changes the docs are automatically changed to reflect the updates. Why make work for the tech writer (and of course the developer[s] who have to review the tech writers changes?) -- and that's if the developer even remembers to tell the tech writer the UI changed.

My point here is that the term documentation needs a definition, and the definition itself might be a rather large discussion.

[briandominick]

I think this is a key question that I only recently realized documentarians really do not get, and I was definitely not getting it when I first started writing this. A lot of people think documentation is just APIs or something, and a lot of other documentarians never think of APIs, just instructionals and long-form/conceptual stuff, with some reference material strewn in. My system is intended to mix the two, and a lot of my newer writing (like the diagrams) makes that clear.

I'm with you on the UI strings as a good example of single-sourcing docs and code. That's what my book is supposed to be all about. I think it didn't start out there, and I'm not sure that was or should be a focus in the early chapters. I definitely need a better definition of documentation, though.

[lief-erickson]

Oh, I completely agree, UI strings are not something that are immediately seen as documentation, and truth be told, they're not "documentation." But they're needed by the documentation. Getting engineers, developers, and especially software architects to see them as needed by various teams, who may have specific requirements, then DocOps is doing (part of) its job. Again, the goal here is to speed up the production process, reduce the review effort required, allowing everyone on the team to contribute higher value work to the project. Getting people to share UI strings in just one visible way to do it. It's also easy to demonstrate the amount of work needed to do by Tech Pubs when UI strings change (and the amount vastly increases when screenshots are considered).