Consider adding content to help new users with an opinionated guide to building a site.

[cfjedimaster]

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.

[MattWilcox]

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.

[darthmall]

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.

[darthmall]

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

[dwkns]

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.

[uncenter]

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!

[nielsbom]

@darthmall the person giving that talk (Daniele Procida) has excellent documentation about these different kinds of docs: https://diataxis.fr/ (surprising huh? 😄 )

[loriortiz]

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.

[quinnanya]

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!

[spencerflem]

@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.

[uncenter]

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.

[MattWilcox]

Just to note, the book Eleventy By Example does a good job of walking you through an introduction and practical example of using 11ty.

[ironnysh]

I'm also happy to contribute! How should we proceed?

[MattWilcox]

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