Why Documentation Shouldn't Feel Like Plain Text

Documentation is one of the most important parts of a software project, yet the experience of writing it often feels far behind the experience of writing code. Modern IDEs provide features such as diagnostics, syntax highlighting, code navigation and instant feedback while programming, but documentation authors frequently discover broken links, invalid references and structural issues only after generating the final documentation.

This talk explores how language-server technology can help bridge that gap by bringing IDE-style feedback and navigation to documentation workflows. Through the lens of my Google Summer of Code project with SourceKit-LSP, I will discuss how documentation can be treated as a first-class artifact rather than plain text, enabling richer tooling and a faster feedback loop for writers and maintainers.

I will begin with a brief overview of my journey into open source and how it led me to work on developer tooling through GSoC. From there, the talk will focus on the broader ecosystem of documentation tooling: what documentation compilers are, why documentation workflows often lack the tooling available for source code and how language servers power modern editor experiences.

Using DocC, Apple's documentation compiler for Swift and Objective-C, as a case study, I will explain how language-server concepts such as diagnostics, syntax highlighting and navigation can be applied to documentation files. The talk will also cover the architecture of SourceKit-LSP, the challenges involved in extending language-server functionality to new document types and the design decisions made while implementing support for DocC.

The session will conclude with a live demonstration showing how documentation authors can benefit from IDE features directly while writing documentation, reducing context switching and catching issues before documentation is built.

• Why documentation should be treated as a part of the development workflow rather than plain text.

• How language servers power features such as diagnostics, code navigation, and editor intelligence.

• How language-server techniques can be applied beyond programming languages to documentation and other structured content.

• What challenges arise when extending language servers to support new document types and workflows.

• Practical insights into contributing to large open-source developer tooling projects.