Technical documentation requires readers to take in a lot of complex information. To make documentation consumable, readers need a logical flow of pages to navigate. To help readers get from one page to the next, we need a simple and reliable system for creating references between pages. This article proposes an intuitive and stable page referencing system for documentation.
A Standard Project Structure for Documentation
If you browse the source code of software projects, you’ll notice that projects built for the same platform share a common structure. This practice makes projects immediately recognizable. It also matches the assumptions of tools that build them. No such structure exists for documentation. To reduce friction when writing, and to make way for a stronger ecosystem of tools, this article proposes a standard directory structure for documentation projects.
Content is Sovereign
Content is king. That we know. But we forget that content is also sovereign. Too often, that independence gets trampled when producing a documentation site, giving rise to a content monolith. In this article, we present a new way of organizing content for a documentation site that respects and utilizes the content’s sovereignty.