In every company I’ve encountered, documentation is a recurring challenge. It’s a complex topic: creating documentation is labor-intensive,

In every company I’ve encountered, documentation is a recurring challenge. It’s a complex topic: creating documentation is labor-intensive, but keeping it up to date is even more demanding. This often leads to outdated or non-existent documentation.

For years, I’ve worked on improving documentation processes. My approach focuses on enhancing tools to make them more efficient and incorporating automation. In many cases, documentation can be derived directly from infrastructure, minimizing manual data collection and allowing people to focus on analysis, commentary, and summarization.

While it might seem like a small detail, I believe a different approach to documentation could bring significant benefits to organizations.

What makes great documentation?

No matter what platform a company uses, it should support all types of documentation: process, technical, or compliance. Choosing the right tool requires considering the needs of all teams. I recommend the following key features:

• Export to PDF.
• Support for macros, even complex ones.
• Integration with APIs.
• Metadata for each document: author, date, confidentiality level.

Why I avoid traditional word processors

The most commonly used tool for writing documents is Microsoft Word. In some cases, I’ve also seen LibreOffice or Wiki-style collaborative systems.

Microsoft Word is undoubtedly powerful, offering countless features. However, its complexity often results in these features being underutilized.

Personally, I avoid traditional word processors for several reasons:

• Incompatible with version control: Their binary data structure doesn’t work well with tools like Git.
• Mixing layout and content: Formatting and content are intertwined, complicating workflows.
• Inconsistent layouts: Achieving uniform formatting can be unnecessarily time-consuming.

I find the combination of content creation and formatting to be inefficient. Authors should focus on writing, not how their text looks, to save valuable time.

Not everything needs to be documented

Over-documentation often highlights deeper process issues. Here are key points for organizations to consider:

• Base skills: Employees should have fundamental skills. Documentation isn’t a substitute for basic training.
• Documentation ≠ Reporting: Documentation should be concise and essential for the company’s operations, unlike extensive reports.
• Readability: Hundreds of unreadable pages are a waste of time. Keep it simple and practical.
• Regular updates: Allocate time for maintaining and updating documentation.
• Standardization over Customization: If every product requires unique documentation, consider standardizing products instead of creating endless variations.

Continue reading the post on Patreon .