The Problem
I inherited a substantial body of documentation for a secure data-transfer software package that used many different protocols and security tools. Engineers had written the documentation directly, so it contained valuable product knowledge but reflected how they understood the system rather than how administrators needed to learn and use it. Some procedures and prerequisites were missing, dense passages were difficult to read, and related information did not yet form a path a reader could follow.
The information architecture problem changed when the base management system split off from the secure data-transfer package. It had previously managed only that package, so the books could contain information about both. Once the management system became a separate product that could support other systems, its documentation needed to stand on its own.
Why It Was Hard
The first challenge was to preserve the engineers' technical knowledge while reorganizing it around what administrators needed to understand and do. Administrators needed the missing prerequisites and complete procedures, but they also needed consistent voice and formatting, clearer organization, tables for complex relationships, and graphics where a visual explanation made the system easier to understand.
The product split made placement more difficult. I still owned both documentation sets, but ownership did not remove the legal boundary between them. Information specific to the secure data-transfer package was not allowed in the management-system documentation. At the same time, duplicating legally shareable material would create parallel versions that could drift as the two products changed and shipped separately.
What I Figured Out
Owning both documentation sets did not make their information interchangeable.
The documentation architecture had to follow the new product and legal boundaries. Material could remain shared only when it applied to both products and was legally allowed in both. Concepts and procedures specific to the secure data-transfer package had to remain in that package's documentation even when the management system was involved in the workflow.
What I Changed
I began with a complete audit and inventory of the engineer-written material. Instead of treating every rough section as a writing defect, I looked for the knowledge underneath it: what the engineer assumed, what the administrator would need to know first, and which product behavior still needed to be verified. The audit exposed missing concepts and prerequisites, incomplete procedures, readability problems, inconsistent voice and formatting, and gaps between related tasks.
The rewritten material preserved the technical substance while reorganizing it around administrator needs. I added prerequisites and procedural detail, used tables and graphics where they made complex information clearer, standardized voice and formatting, and improved navigation between related tasks. I also applied the official branding and templates, added the required legal information, and documented new and changed product information with each release.
For the original product, related material had been distributed across roughly four books. I reorganized and consolidated it into one book so readers could retrieve information more easily and PDF cross-links could connect related content reliably. I then established rules for deciding whether new material belonged in the management-system documentation, the secure data-transfer documentation, or the legally shareable common source. Audience, product and legal boundaries, and release behavior determined that placement.
When the management system became a separate product, I revisited those rules. Each product had its own Subversion tree. Content that could legally appear in both lived in a common shared-content folder and entered the product sources through XML includes. Release tags preserved the source used for shipped versions, and Jenkins selected the appropriate product and shared-content branches for each build. This kept permitted common information aligned without carrying material specific to the secure data-transfer package into the management-system documentation.
The new architecture also prepared the management system to support products beyond the original secure data-transfer package. Its documentation could explain the base system without assuming that every customer used the same package, while the data-transfer documentation could retain the product-specific information its administrators needed.
What Changed as a Result
For the original product, administrators gained one organized book with working cross-links, clearer paths through a technically demanding system, consistent presentation, and the required legal information. After the split, the documentation architecture reflected the new product, legal, and release boundaries even though I continued to own both documentation sets.
That structure reduced the risk that duplicated content would drift across products and made later decisions more systematic. When a component, owner, or release cadence changed, the team had an architectural rule to examine instead of having to rediscover the original rationale.
Evidence and Technical Detail
Making these decisions required a working understanding of secure cross-domain systems, encryption and key management, secure file and stream transfer, Linux administration, networking, PKI and certificates, configuration, installation and deployment, troubleshooting, APIs, configuration formats, and air-gapped or restricted environments. Product builds, procedures, and technical explanations were checked against system behavior rather than accepted solely because they appeared in inherited source.
The broader Everfox documentation work was supported by a nine-VM test environment used to install builds, exercise APIs, run regression tests, validate examples, reproduce customer issues, and distinguish documentation defects from product defects. Source-code reading and direct testing supplied evidence when the written sources or remembered behavior did not agree. Separate product Subversion trees, a common shared-content folder, XML includes, release tags, and Jenkins branch selection enforced the product, legal, and release boundaries in the build process.
