Single Page Docs: Stop the Click Insanity
Multi-page docs are the norm in most documentation framework. However, they aren’t the best tool for the job of creating usable docs. Take for example the docs found on readthedocs.org for Django Fluent Contents. This is a very normal looking sphinx project. Now lets try to find example code for the announcementblock plugin:
Ctrl+F “announcementblock”. Darn, ok, no results. Ctrl+F “plugins”, Nope, Enter, Nope, Enter, Enter, Enter, Enter Click on the link for example code, there it is! Woo!
This style of code docs forces users to guess, click around, or simply leave your docs and use a Google site: search. A better alternative is single page docs like those for Express JS. In this talk I will explore the best patterns and tools for single page documentation. And also explore the features and niceties that take single page docs from good to great.