Revision: 1.1
The Documentation as Code approach suggests that documentation authors should benefit from tools that produce applications from source code. As long as it is justified to compare the process of making documentation with the process of making applications from their source code, tools that work for applications will allegedly work for documentation, too. Therefore, it is admissible to suggest that version control systems, configuration systems, CI/CD infrastructure components work for documentation in the same manner as they do for applications.
It is worth noting that this approach limits itself to plain text formats – a document created in a WYSIWIG editor is out of scope. Documentation as Code relies on a superficial similarity of source code for documentation to the source code for applications.
But there is problem. Although both are plain text, not everything that works for documentation will also work for applications. The fundamental difference lies in what constitutes a product: a state in which all parts work together to bring value. An application as a product is an executable program. To understand the value and capabilities of a program, you have to run it. There is no value in it until then. An application becomes a product only after it has gone through all necessary transformations from source code into an executable unit.
On the other hand, to make sense of documentation you just need to read it in whichever form it is at the moment. Documentation is already a product even when it is still in the form of source code. As a matter of fact, the principle of readability of source code is one of the most essential requirements in all plain text documentation formats.
The Documentation as Code ignores this fundamental difference and suggests that documentation source code be treated as application source code. Moreover, is not hard to find compliant projects, where the documentation files are part of the application source code under the "doc" subdirectory and are to follow all procedures applicable to application source code.
With the main focus on source code, the term Documentation As Code is loose. Following what it suggests, the term Documentation source code built as application source code is more appropriate (but less attractive). The term code, even in the context of software, is more generic than source code. With the broader meaning of code in mind, the definition of *Documentation as code* should also be more generic.
From this more generic perspective, Documentation as Code represents the effort to help documentation authors benefit from best practices applied to the constructing of application code – not from the tools that process the application source code. In other words, the focus moves from the source code to what this source code contains.
This feels like the right path. There are quite a number of principles known to programmers that help improve the readability and structure of application source code. Most importantly: these principles make it easier to reason about the application.
If there are techniques and best practices that make code easier to reason about then documentation authors definitely need to be aware of them because making it easier to reason about text is also an extremely important task.
As Code: Modules
When code grows in complexity, it must be refactored. This means that it should be rearranged to offer better readability while still producing unaltered behaviour. Refactoring is crucial because programmers must have a clear understanding about how efficiently the application performs its tasks. By placing code into modules, you combine features that belong together. Modules also help represent the whole code as one structured unit, which makes it easy to maintain and develop the application.
In case of documentation, a module is nothing more than a named section with content: text, tables, figures, etc. Documentation is usually organised by such modules already, but the documentation author can certainly benefit from refactoring. In practice, it means that the documentation author must verify if the content of a book, or even a section, is properly associated with appropriate headings and the headings themselves enable readers to grasp the logical structure of information.
As Code: DRY
DRY stands for Don't Repeat Yourself. The conforming code does not repeat the same functional segments. Instead, the segments that may appear more than once are placed in functions and these functions are called to do their job wherever needed.
In documentation, this principle applies not only to the content but also to the way how source code is organised. A fragment of text which is repeated multiple times can turn into a separate section which is referred to wherever needed.
There are cases when cross-referencing is not an option. For example, there
is an important admonition so essential that the reader should always see in full text. The DRY principle works on the source code level, too. By utilising the import feature which is found in many plain text documentation formats, fragments of text are stored in separate files and are imported into the right context. The documentation author comfortably sees only the import instruction. The reader sees the whole text of the fragment in all places where this text ought to be.
As Code: Variables
A variable is a piece of data accessible by a name. A well named variable becomes a piece of information in code. In code, variables are indispensable. If named properly, they help better understand the purpose of code and the flow of the application.
In documentation, variables appear in two variations. Every term defined in documentation serves the same purpose and represents its definitions everywhere it is mentioned.
Even a better representation of a variable is a placeholder which is used to substitute for any piece of text in documentation source code. Mature documentation platforms support placeholders to enable documentation authors to use short useful names in place of hard to type sequences of characters: file paths, complex terminology, or clichés.
Upshot
There are many other useful features that characterise well-written code that documentation can make use of either in content or in its source code: consistent identifiers, naming conventions for files of different types, encapsulation, and many more. When applied these best practices, techniques, and principles may open new possibilities for improving productivity.
Consistent and formally well structured code is easy to automate and analyse not only by the tools that work on application source code but also those that work with textual data.
Documentation Source Code Approach Revisited
What is probably unexpected is a high possibility of a conflict between the interpretation of Documentation as Code given in this perspective and the more popular definition.
Concise modular documentation with placeholders and other useful features adopted from best practices for constructing applications is much harder to review for a programmer or any other subject matter expert. But it is going to be quite comfortable for documentation authors. Such source code defies one of the key advertised benefits of the popular Documentation as Code approach: subject matter experts should be as comfortable reviewing documentation when they do code reviews.
The fundamental problem of the popular Documentation as Code approach is that it chooses to ignore the fact that documentation is already a product even when it is still source code. In this form, it brings value to documentation authors themselves. For others, it must be transformed into document as a site or documentation as a book.
Yorumlar