Documentation frameworks

While documenting new products or updating existing ones, I’ve adopted the following documentation frameworks:

• Diátaxis
• Docs as Code
• DITA

Diátaxis

Diátaxis organizes documentation into four categories: tutorials, how-to guides, technical references, and explanations. The framework helps decide what to write, how to write, and how to organize documentation.

Adhering to the Diátaxis framework strictly is not required - you can adapt it based on the product’s needs. Sometimes, writing a tutorial is not possible, so just skip it! Or, if a reference isn’t required, you don’t have to write one.

My work at Adjust

I worked with my colleague to rewrite articles in the Developer Hub using the Diátaxis framework. We were able to structure the information in a way that worked well for our clients.

References: From old content layout | Archived link to new content layout | Archived link

Docs as Code

Docs as Code is a framework that treats documentation like code. Writers typically use the same tools and processes that developers use for writing code. This approach involves creating documentation in Markdown text files and storing them in source code repositories such as Git. It promotes collaboration among developers, writers, and other stakeholders, ensuring that documentation is updated and accurate.

Docs as Code supports version control, automated testing, and continuous integration, ensuring that documentation remains synchronized with code updates and always stays up-to-date. This approach allows product managers or writers to block new feature merges if they don’t include documentation, encouraging developers to integrate documentation as part of the product.

The Docs as Code framework is used for Developer documentation, which usually includes SDK and API documentation.

My work at Adjust

I collaborated closely with my team to move the Developer content in the Help Center to its own separate Developer Hub. We brainstormed and finalized the design and structure of the new Developer Hub.

References: Developer Hub | My GitHub commits

DITA

Technical writers use DITA (Darwin Information Typing Architecture), an XML-based architecture to create and manage topic-oriented content. DITA maps and topics are XML files, where images, videos, or any other files are inserted as references. DITA is widely used in technical documentation due to its ability to create reusable content. This ensures consistency, minimizes duplication, and improves maintainability.

My work at PTC

During my time at PTC, I’ve used DITA extensively to document multiple flagship products, such as ThingWorx Flow, ThingWorx Analytics Manager, and ThingWorx Utilities. I’ve had the opportunity to design the information architecture of ThingWorx Flow and ThingWorx Analytics Manager from scratch.

References:

• Concept topic | Archived link
• Task topic | Archived link
• Reference topic | Archived link