Legacy Documentation

Within an enterprise documentation system, legacy documentation refers to monolithic document files and/or document platforms and storage systems that fall outside both the general-purpose and specialist documentation platforms.

As such, typical legacy documentation platforms include:

• Microsoft Word
• Google Docs (pure SaaS, not a file format per se)
• OpenDocument (Libre/OpenOffice)
• WordPerfect

They may be served through a variety of means:

• HTTP Servers
• FTP Servers
• Local drives
• LAN Network drives (e.g., Samba)
• WAN Network File Systems (e.g., NFS)
• Cloud Blob Storage (Amazon S3, etc.)
• Proprietary platforms
  • Microsoft SharePoint
  • Microsoft Teams
  • Google Workspaces

DocOps Automation

What characterizes legacy documentation from that within the general and specialist scopes is that they are monolithic and render-oriented. They offer poor support for DocOps automation since they are not intermediate document formats which are practical to decompose, generate, and recompose dynamically.

DocOps automation efforts focus on transferring legacy document files from and to their storage systems, and then converting from and to various document encoding formats.

Monolithic Nature

Flagship wiki engines, as well as formats such as AsciiDoc or LaTeX, encourage organizing documentation in a modular fashion so that common content can be reused. Legacy document formats, instead, are monolithic; common content is copy-pasted rather than referenced.

Reasons to Automate Around Legacy Documentation

The reasons as to why DocOps engineers have to deal with legacy documentation, as opposed to encouraging participants to maintain content using the main documentation platform are multiple fold:

• Historical documents: the bulk of an enterprise’s body of documentation is likely to have been produced before the advent of DocOps best practices.
• External documentation sources: legacy documentation may originate from regulators, partners, auditors, and so on.
• Senior participants (the HiPPO effect): the likes of senior executives and those in the legal function are unlikely to be persuaded—let alone coerced—into adopting a modern documentation platform, which may be lacking the templates and ‘free formatting’ options they deem fundamental to conduct their activities.
• Security dogma: inexperienced professionals in the security and risk functions, unaware of the principle of minimal secrecy often take the knee-jerk reaction of demanding documents to be produced using monolithic file formats (classified as public, internal, confidential, etc.) so that they can be saved to a folder-oriented platform such as Microsoft SharePoint in which further controls can be applied.