Maintain ​documentation in the evergreen state to continue as a reliable engineering asset

Metadata governance
Consistent schemas, ownership, lifecycle control.
Structured repositories. Faceted search.

Metatagged discovery
Search that understands platform, version, and information

Lifecycle governance 
Documents go from draft, evergreen, to deprecated states.

​
​Documentation stay accurate as your platform grows.

Effective information architecture (IA) acts as the crucial "skeleton" for documentation, turning scattered resources into findable, compliant, and scalable intellectual property that eliminates the costly "search overhead cost".
​[see references below]

How did we get here? 

#TLDR

While the cost of not finding information is enormous; it is usually hidden within the enterprise as overhead.... and this is why this loss is rarely perceived. (See valuation gap.)

​
Q: Was it always hard to find the right information at the right time? 

A: No. Before the advent of wikis in 1995, we tightly controlled information. When information was on paper.

• Information was regulated and easy to pull out any previous approved information file, whether it was a user guide, blueprints, or a BOM (bill of materials). 
  
   > The Wiki founder's  goal, according to a 2012 WIRED interview, was to put ultimate control of their wiki pages in the hands of its users, rather than one centralized hub. 
  
  > Read the cost of removing the centralized hub, "The High Cost of Not Finding Information", published in IDC, by Analysts, Susan Feldman and Chris Sherman. 

 

• Read more to understand why this remains a hidden problem.
• Learn how to show leadership this cost and take steps to correct needless waste.

Graphic depiction below shows how information architecture is often fractured by letting personal and short-term decisions drive the storage design.
​

Evergreen information framework

Categorize knowledge items (onboarding, runbooks, release notes, quickstart guides, etc.) as reliable engineering assets.

Four major steps

1. Diagnose repository chaos
2. Design metadata architecture
3. Implement faceted discovery
4. ​Establish governance automation

(These four steps are high level concepts; ​there are many smaller steps in practice and depend on your particulars.)

Diátaxis is a modern word coined for software and technical documentation design. It translates to "arrangement" or "layout" in Ancient Greek.​

Diátaxis
A systematic approach to technical documentation authoring.

​Diátaxis prescribes approaches to content, architecture and form that emerge from a systematic approach to understanding the needs of documentation users.
Diátaxis identifies four distinct needs, and four corresponding forms of documentation:

• tutorials; a learning oriented experience.
• how-to guides; guides a users' action to get something done.
• technical reference; provide theoretical knowledge users require for truth and certainty of that specific technical environments
• explanation; provides a deeper and wider insight on a subject. An explanation file is also known as a reflection on the subject matter. It often bridges a concept with another. It is not meant to guide or teach.

It places them in a systematic relationship, and proposes that documentation should itself be organized around the structures of those needs.