If you have a moment, I’d love to hear why you think these are exceptionally bad docs, and some examples or thoughts on what you feel are excellent docs!
We use and financially support 11ty at work, so if it’s something I can manage, I’d like to help make the docs better over time.
I have a long history of improving extensive documentation for my past employers, and the first thing I always start with is a general question: Can I follow the stream of thoughts when reading the docs? Does it have a well-prepared welcoming page that can guide me to the information I need? (Sometimes you are just curious about release dates, and other times you might have forgotten the name of a plugin).
Documentation, as I understand it, should be a pleasing experience that takes you on a journey, allowing you to decide how deep you want to go.
The issue with 11ty's documentation is that every single page is overwhelming with technical details introduced right away. There is no foreplay, no gentle introduction—just straight into the details. I hate it; it makes me feel like it’s designed as a gatekeeper of knowledge (I've seen this in my previous companies too).
Designing documentation should start with simple ideas that gradually lead to more complex concepts (just like in coding, where we start with variables and functions before moving on to more complex structures like classes and logic). Simplified diagrams are also a very welcoming idea for a starter page.
To make it more 11ty-focused, their documentation is missing:
1. A welcoming page explaining what you are currently seeing and what you can expect.
2. A simple go-to project, rather than an overwhelming list of 30+ startup projects (why not just showcase a simple blog with one post?).
3. A "Set up your first project" page (I’ve chosen my first project, where should I go next?).
4. Instructions on how to extend your project (covering advanced topics like modules).
5. General organization—the whole page is cluttered with too many links, text blocks, paragraphs, and images.
6. Explanations of basic concepts (for example, it took me three days to understand why some pages have three or more syntaxes).
7. ... and more, but I just can't stand even looking at their docs
A really good example of documentation is React: https://react.dev/learn