Consider adding content to help new users with an opinionated guide to building a site.
cfjedimaster opened this issue · comments
Per a discussion with Matt Wilcox on Mastodon (https://mastodon.social/@raymondcamden/109999585668301666), he raised the issue that one thing missing from the docs is a proper "start here" guide. He went on to say that the docs have no opinions which could leave some users a bit unsure how to start.
Going on, he used the Astro docs as an example, https://docs.astro.build/en/getting-started/, saying:
Why is Astro so well loved? https://docs.astro.build/en/getting-started/
That's one reason ^
- Start HERE
- Concepts
- Build a blog
THEN the nerdy guts.
Speaking for myself, I can see some logic in this suggestion. Eleventy does have a getting started, https://www.11ty.dev/docs/getting-started/, but it's possible it could be expanded a bit. You still want to get new users to a 'quick win', but the guide does seem like it could be a bit deeper perhaps.
This is something I'd like to help with, but really want to just start a discussion to see what other's think.
Pretty spot on :) I think there's a good reason why the Astro docs URL defaults to the "Learn" content, and not the "docs" content. And that's also a strong component of why Astro adoption is high, and well liked. It is very clearly aimed at getting people on-board who do not already know the concepts involved.
Here's a tangent that informs my thinking on documentation (in general), and why it's primarily a solution for people who already have a solid grounding in whatever's being documented...
Documentation is a dictionary - not a curriculum. A dictionary is only useful if you know what to look up and why.
If you want people to learn a thing, you can't only define the components of the topic. You can't just write a dictionary. Docs alone aren't enough. You can't learn how to write poetry from a dictionary even if all the definitions are there.
You have to start from defining a core problem, then the concepts around it, then introduce solutions, then show how those all integrate into the whole.
At that point, the dictionary becomes useful.
I definitely agree. The “Getting Started” section in the official docs seems more like a demo of how Eleventy can be zero config. Which is great, but it is not an example of how one would want to work on a site long-term.
There is also the Tutorials section of the docs, but this suffers in part from the paradox of choice. There are a lot of tutorials listed here, and none of them are official, so how is someone new to Eleventy to choose?
Furthermore, some of these are just blog posts, which really represent the state-of-the-art at a certain point in time. Blog posts are rarely kept up to date.
I know at one point there had been some discussion of using Open Collective funds to have Andy Bell/Set Studio update Learn Eleventy from Scratch. Learn Eleventy from Scratch is definitely one of the more comprehensive tutorials I’ve come across (maybe too comprehensive? Gulp and Sass seem like a bit of a distraction for an Eleventy tutorial…) and is usually the one I point people to when they come into the Discord asking which tutorial they should follow. That said, a one-time update just kicks the can down the road again. So I think an official tutorial that is maintained with all of the docs would be great.
Possibly relevant to @MattWilcox’s point about documentation being a reference, not a curriculumn; I’ve always liked this breakdown of four different types of documentation: https://www.youtube.com/watch?v=t4vKPhjcMZg
- Tutorials
- A complete lesson that walks you through accomplishing some task—e.g.Learn to build a website in 11ty
- How-tos
- Short recipes for accomplishing very specific things—e.g. How to add Sass as a custom template engine
- Reference
- Most of what we think of as documentation; the dictionary to which Matt refers—e.g. a list of all of the WebC attributes and what they do
- Key Topics
- Higher level important concepts—e.g. The data cascade
One of the great things about eleventy is that you can do things in lots of different ways. This is fantastic if you have experience and you are coming from other platforms. But for beginners it can be very confusing.
One of the reasons Rails took off was that it favoured convention over configuration. There was a Rails way. It made it easy to get started, to progress and because nearly everyone did it the same way it was easier to get support.
I would never want to lose the flexibility and configuration that eleventy allows, but having an opinionated way (folder structure, template language, CSS & JS asset pipeline & deployment) of getting a site live would make the on-ramp that much much easier for beginners.
Then once you've learnt a good way to do things, then you explore all the other ways of achieving the same thing.
I think this would also be a good opportunity to reinforce some of the ideals that eleventy has at it's heart. HTML first, use the web platform, progressive enhancement etc etc.
I'm also happy to help.
I've also been thinking recently about how to fix some of these issues. I saw a post on Mastodon that mentioned how difficult it was to create a site. My thoughts are that because 11ty is so unopinionated (which is wonderful), different tutorials and starters can give conflicting ideas on what to do. Not fun!
I mentioned in the community Discord server that I have been working on a new tool to (hopefully) solve some of these issues. The tool generates the structure and basic asset/asset pipeline needed for a site. I have a plugin/addon system in the works as well. Still a lot of work to do, but if you want to give a hand I'd appreciate it! Check it out here. Feedback welcome.
I also agreed that Learn Eleventy from Scratch should be a priority. Such a great comprehensive resource (although, I'm too not to eager about the end product it gives... it might be better if it's simplified a bit to building a blog instead of a company website). I am happy to help on that end too!
Thanks for bringing this up @cfjedimaster!
@darthmall the person giving that talk (Daniele Procida) has excellent documentation about these different kinds of docs: https://diataxis.fr/ (surprising huh? 😄 )
Stephanie Eckles blog tutorial listed on the Eleventy site as official, and Little Stix's Crash Course Were the most helpful to me getting started with Eleventy. The Andy Bell tutorial looked great but the disclaimer at the top about its being outdated caused me to look elsewhere. Now that it has become more complicated, good how-tos are needed as next steps... and updated tutorials, if beginners are to get started with 2.0. Happy to help if I can.
Hi, I was directed to this thread from a conversation on Mastodon -- this is exactly the sort of thing I was / still am(?) looking for. I've made several sites, but it's been a lot of guesswork (and begging developer friends for help when I get completely stuck) and there's a set of common things that I at least need on the kinds of academic sites I build where I'd love a clear example of one reasonable way to do it. Happy to write user-facing prose if someone else could lend a hand with the code!
@quinnanya I'm happy to help with the code. I'm a beginner to 11ty, but not programing and while I really like the project and it's goals it has not been very easy to learn. Before doing anything though, I want to make sure this is something that the project wants and that there's someone more experienced to double check things.
I'd love to lend a hand too! I'm hoping we can start some sort of documentation "renovation" project and overhaul the way the docs are structured and written before Eleventy v3 is released... happy to pitch in wherever necessary. I'm currently trying to make some cleanup PRs to the https://github.com/11ty/11ty-website but it is slow going.
Just to note, the book Eleventy By Example does a good job of walking you through an introduction and practical example of using 11ty.
I'm also happy to contribute! How should we proceed?
I am still very (very) early in learning things so I'm not likely to be useful on this one yet I'm afraid. That said, if the goal is to have an easy on-boarding then the way that the Astro docs deal with that would be a smart thing to reference at least in terms of what topics are brought up first, and how in depth to go for that sort of content before passing off to the existing docs.
Also referencing the outline of something like Eleventy By Example might work well.
- Installing (and, what LOADS of projects miss here... updating)
- My First Realistic-ish Output
- Introducing templating concepts to refine that
- Introducing data cascade concepts to further refine that
- Introducing Collections for making Blog-like content
etc etc
Definitely important to have a more structured and ordered walkthrough but equally as important is a reference page (e.g. https://docs.astro.build/en/reference/configuration-reference/). It's frustrating to have to sift through lots of text just to, say, find the options I can pass to a certain function.
There's also a lot of super useful content here and on Discord. Thinking about @pdehaan's example repos, for example 🙂
Maybe we can start mapping what's available (and still relevant), and arrange it into these 4 "buckets".
My thoughts...
Guide
Every project needs to start off with the very basics. Installing, setting up, adding templates/pages, and deploying. We can link to the starter tutorial here, but that's it, keep things simple. It would help to have a create-eleventy CLI to bootstrap this. I gave this a go with my create-eleventy-app a while back but didn't quite get to where I wanted it to be. There also should be a space here for some of the pages that already exist on the docs:
- Pagination (what properties exist?)
- Permalinks (how to use them? how are they generated by default)
- Eleventy Supplied Data (what data do i have access to and where? this also could go down in the reference section below)
- Passthrough File Copy
- Filters (adding them? accessing them? using them? which filters exist out of the box?)
- Shortcodes (same as above + some common usage examples e.g. callouts/notes)
- Transforms (same as above, examples could include minifying output assets)
Tutorial(s)
I think this part really comes down to understanding what people are trying to accomplish with Eleventy. For the most part, it is personal blogs and websites (that people start out with at least). So I think something like https://learneleventyfromscratch.com (or my updated version https://learn-eleventy.pages.dev/) is something we can look at. A table of contents could look something like this (adapted from @MattWilcox's previous comment):
- Installing and initializing a project.
- Running the project for the first time, explain what is happening, explain the output.
- Introduce the concept of templates, the various template languages, and front matter. Probably also a good time to explain permalinks (and the trailing slash / directory thing some people get stuck on).
- Introduce the data cascade concept (front matter data, directory data, global data, computed data, etc).
- Introduce collections (this should be a guide about a blog, after all).
- Introduce using plugins to say, add an RSS feed.
- Introduce higher level concepts like pagination.
- Introduce a more complex build system inside Eleventy, processing assets like SCSS/TS files (SCSS for styling, TS for client-side scripts), as well as how to utilize passthrough file copy (for copying favicons or something).
Not only should there be a starter tutorial, a tutorial for writing plugins would be neat - I've written a couple plugins, some in raw JS but also some compiled from TS so I can lend a hand here as well.
Reference
Ultimately, once you've understood the basics, the primary purpose of the documentation is to quickly resolve any questions you have about... what is that one property/option again? How do I disable this? Just questions that can be resolved by, as I previously mentioned, a reference section. A table of contents for that could look like:
- Configuration (all about the configuration file).
- CLI (what options are there, how do I run it, etc).
Examples
Then, having some examples is great. We can link to eleventy-base-blog, some up-to-date / monitored / verified templates/starters that are still maintained...
I'd like to chime in and add my two cents regarding the idea "getting started" with Eleventy. One thing that I think is skipped, particularly if we're trying to attract and provide guidance to those who have never developed a website or done any kind of software development before, is the basic notion of a development environment. We may want to consider describing node.js and its role in the use of eleventy and the basics of having a code editor. I just looked at the 11ty getting started area and the Astro sequence of getting started and Astro does a far better job at this particular entry point than Eleventy, in my opinion. Eleventy, while it says that node.js is required, just jumps right into an npm command. I think it would be very beneficial to the goal of expanding the community of Eleventy adopters to make the entry point more accessible to the complete newbie.
Adding on to Bob, here is another example of guiding users through installing pre-requisites: https://learn-eleventy.pages.dev/lesson/1/.
...One thing that I think is skipped, particularly if we're trying to attract and provide guidance to those who have never developed a website or done any kind of software development before, is the basic notion of a development environment...
I am of two minds on this, because of the complexity, but there's a very big reason why I like to use Docker/DDEV for my other development work. And it's because the entire dev environment is already sorted for any and every project, so the only thing I need to do to start work on any of our PHP/MySQL projects is to cd into the newly checked out folder and type ddev start. I do not need any npm/php/mysql/apache or anything else. There are never any conflicts because I have one project needing node 12 and another node 20, or php5 vs 8.2. It's all isolated per project and done automatically.
I think there is a ton of value in this approach, where the one and only requirement of the machine is that it has Docker installed.
But, as I said, two minds on if that's too much for "a newb", but if there was a properly configured Dockerfile in an example project... then you don't need to worry about the user installing the right npm for this version, and configuring PATH or any of that other stuff.
...One thing that I think is skipped, particularly if we're trying to attract and provide guidance to those who have never developed a website or done any kind of software development before, is the basic notion of a development environment...
I am of two minds on this, because of the complexity, but there's a very big reason why I like to use Docker/DDEV for my other development work. And it's because the entire dev environment is already sorted for any and every project, so the only thing I need to do to start work on any of our PHP/MySQL projects is to cd into the newly checked out folder and type
ddev start. I do not need any npm/php/mysql/apache or anything else. There are never any conflicts because I have one project needing node 12 and another node 20, or php5 vs 8.2. It's all isolated per project and done automatically.I think there is a ton of value in this approach, where the one and only requirement of the machine is that it has Docker installed.
But, as I said, two minds on if that's too much for "a newb", but if there was a properly configured Dockerfile in an example project... then you don't need to worry about the user installing the right npm for this version, and configuring PATH or any of that other stuff.
I don't teaching new users Docker is the way to go. Needless complexity for just a few steps on a separate page to install a terminal/Git/Node.js.
Well my point is that you don't need to teach docker at all if you have a Dockerfile in a project. We have devs using Docker/DDEV to run projects who have no understanding at all. Their entire thing to get started on any project is:
- copy the project to their machine (via git, but that is irrelevent)
ddev start
That's it. They need know nothing more. And I think that 11ty's dependencies (node) are so small that a simple Dockerfile should cover everything without needing editing. That way, getting started with an 11ty project doesn't require getting node on a machine or wrangling path/version etc. Just ... "install Docker, copy this file, go"
But yes... two minds as to if that's a tangent worth taking.
I'm against giving people tools they don't understand. And for the record, I've yet to see any other framework/tool in the frontend web dev space take that approach.
I do like how easy Docker makes it to get a working environment, but my concern would be that it adds a lot of deferred complexity. The user can’t ignore Docker forever, only up to a certain point, and then they’ll abruptly have to learn a lot of technical concepts that have nothing to do with Eleventy.
That said, I think Docker would be an excellent learning aid. It’d be a quick and easy way to show how a basic Eleventy project works, before (or, depending on how the guide is structured, during) the explanation of how to set one up whether inside or outside Docker. I personally like being able to tinker with a functioning example right away, even if I don’t understand all the details yet, so that I have something I can keep referring to as I learn.
EDIT:
It seems my wording was somewhat ambiguous, so I’d like to clarify that I see any use of Docker as a means to quickly demonstrate the basic functioning of Eleventy, not as a replacement for teaching the user to set up an Eleventy project the normal way.
Yeah, one thing I like about 11ty is that all it needs is a working Node installation. So its not like installing node vs installing docker would be that different in terms of hassle.
For things that need, eg. a running SQL database there's a lot more of an advantage
One thing that could be really cool is if we somehow got it working would be a totally online environment like MDN has for their examples
Or really, what I think the docs are missing a lot of that wouldnt add a lot of complexity, is examples of output. Especially for the WebC docs you can see what the template is but not what it renders to. Even a static version you can't change would be very helpful.
Well the thing is we are assuming that the user doesn't have conflicts - that they don't have a project requiring node 18 and then 11ty 3 needs 20. Which then means delving into nvm etc.
Docker is isolated, and simple as long as a config file is provided (and there are many projects using DDEV - which is a docker abstraction - precisely because of this (CraftCMS has it as default for example).
Anyway; somewhat tangential! The docs covering any basics will help.
(Luckily, 11ty@v3 only requires Node 18!)
I see what you mean though. I think an ideal solution would be to have a standard guide through Git and Node and all that, but link to an alternative guide for setting up with Docker (if the reader is more familiar with that) at the top.