Description
I'm finding it difficult to find a "way in" to the docs.
- /docs landing page is the place for a guide to the documentation section itself, not the place for a general pitch about why to use Eleventy
- Docs aren't organized into a logical sequence
- Getting Started next steps could be improved
I started with the /docs landing page and the Getting Started page of course. For most projects, either the landing page or the Getting Started kind of serves as an intro to the rest of the documentation, but that doesn't feel like the case here. The bigger issue is that, if you just go through the docs pages one by one in the order listed in the sidebar, the articles don't build up on each other in a logical order--each one expects you to already know concepts from other articles, so I end up having five tabs of docs open and none of them are giving me the "basics".
(My goal is to go through and solidly learn Eleventy as a system, rather than just start blindly hacking on it and do a web search for each little thing I'm trying to do, but the docs seem to be written in a way that favors just answering individual "how do I do this" questions and never explains broader concepts.)
I do appreciate the 'next steps' section on Getting Started! Admittedly, I made the mistake of overlooking it to go click on the tutorials instead, and maybe I would be less confused if I had gone to read the Layouts page right away after Getting Started. (I watched the 6 min tutorial video, thought "now what", went back to the docs home but didn't see any guidance there, and then started just going down the sidebar.) But even still, the layouts page suffers from the problem I mentioned above: it's written with the expectation that you already know about the includes folder. I would expect that folder to have been introduced either in Getting Started, or in a page that's listed before this one in the sidebar, but it's not. There actually isn't even a link here to any other page that would explain what that folder is!
Effectively, the "first page" of the docs (according to the layout of the sidebar) is either the "Working with Templates" section overview--which is easy to miss and think it's just a heading--or "Add CSS, JS, Fonts". Working with Templates could be a good place to put some introductory information, but right not it doesn't have any unique content, so I'll say Add CSS, JS, Fonts is the starting page currently. But it's really not well suited for that role. Without any intro to the folder structure that Eleventy expects, I was left confused about where to put these files that it refers to creating. It also suggests using a template, but at that point I was still confused about what the heck "template" even means in Eleventy or where to put those either. It doesn't explain what it means by "bundling" (maybe I'm just too much of a novice to not already know?). It also took me some time to understand from this page that "oh, you just write a normal CSS file like you would for any other HTML site, the unique part is just telling Eleventy how to include it in the output". (I'm getting the idea that the way Eleventy works is to just process various formats of input into a set of HTML files, but I don't think I've seen that stated anywhere.) I'm guessing you put it near the start of the docs because it's something everyone has to do, but it doesn't do anything to help understand the concepts of how Eleventy works. Also, if it's so necessary to use the info on this page to include your CSS (not "necessary for Eleventy to run" but necessary in the sense that realistically nobody wants to publish a site without CSS), then why isn't it mentioned in the Getting Started?
See also the other issue I just submitted, #3093, about some ways that Getting Started left me with a bit of confusion about templates.
Practical suggestions
- Add a new page to the top of the list of docs that explains general concepts
- What Eleventy is actually doing when you run its NPM command; what the inputs and outputs are; a BRIEF description of its purpose or other content from the "why Eleventy" page; maybe a short overview of the development and deployment workflow
- Go over the way Eleventy expects you to structure your working folder (where to put different kinds of files) and lists all the special folders like _includes. also mention any other assumptions or expectations Eleventy might have about the way you use it.
- Alternatively, take the "why Eleventy" page and make it the first page of the docs, with this intro to general concepts being the second page - but tbh that whole page feels more like a sales pitch than actual documentation
- Also include near the top of the list either a link to the getting started page, or preferably, a separate page that just covers all the general concepts (e.g. what a template is) that are covered by Getting Started
- Replace the /docs/ landing page with something more like a table of contents. It should mention general pages like the glossary and tutorials, then list the different sections of docs in the order they're meant to be read.
- There should, ideally, be such an order--if someone goes through all the docs in the order they're written on the overview page, then there should never be a situation where they need to read a later page in order to understand an earlier page.
- If you want me to, I'm willing to read through the docs in the order they're currently presented and flag every time something is mentioned that hasn't been explained yet.
- Ideally, it would be good to reorganize the docs so that there's a "basics" or "fundamentals" section. This could include any conceptual explanations and basically any info that's necessary for the average workflow of creating a basic site. For example, I think "Add CSS, JS, Fonts", "Layouts" (but not "Layout Chaining"), and "Collections" would belong in here, maybe along with one or two pages from the Data section.
...all that said, I'm still a novice dev and not some kind of documentation expert, so take this all with a grain of salt lol. These are just some things I personally find helpful/preferable in documentation. No need to justify things if you disagree with my suggestions!