11ty documentation refresh

[d3v1an7]

Why does this ticket exist?

Sentiment about the current 11ty documentation forms into two somewhat conflicting groups:

• Newcomers find the learning curve overwhelming, and
• Those with more 11ty experience struggle going deeper

What is the intended outcome of this ticket?

11ty documentation is updated to ensure newcomers are able to gain an understanding of 11ty basics, and use tutorials to make something useful or fun. Those looking for more specific details can find what they need easily.

What are some guiding principles to getting this done?

• Inclusive: Concepts, language and tone are clear, inclusive and accessible by default.
• Iterative: Perfect is the enemy of good.
• Light: 11ty supports the indie web and the tone should reflect this! Without sacrificing clarity, the tone should be slightly more weird and fun, less robotic and sterile.

Proposed first steps

1. Create a mini style guide, providing examples of principles above (example)
2. Audit existing 11ty documentation, code examples and information architecture, taking into consideration the intended outcomes and linked issues
3. Determine scope of change to existing site and content, if a temporary interim site/subdomain would be preferable, etc
4. Based on outcomes from 2 and 3, create the list of work that needs to get done and go do it!

Out of scope

• Deep API/function references (i.e. Configuration Docs Do Not Reference addTemplateFormats API 11ty-website#1697). A potential path forward here is an audit of current JSDoc usage and some kind of build time scrape’n’shape, but this feels like a separate piece of work.
• Deep expansion of existing docs. Selfishly, I’d love a guide on how to break down debug output, how to identify performance bottlenecks, etc – but I think surface level updates across the board is already a large chunk of work – unless individual contributors put up their hand to expand/go deep on a particular topic, we should avoid deep expansion for now.

If you're able to help out with any of the proposed steps, or disagree with the approach, or just want to say hello, please leave a comment!

[d3v1an7]

The tickets and feedback listed are from a quick scan, and is by no means exhaustive! If I've missed anything, please link back or leave a comment :)

Linked tickets

• Ambiguity in language on File Passthrough docs 11ty-website#462
• Make "Starter Projects" page useful/trustworthy 11ty-website#1594
• Feature Request: Add additional sort options to Starter page 11ty-website#1227
• Add warning to collection API ".getAll()" 11ty-website#980
• Docs: “Global data files” should address non-camelCased filenames, name collisions 11ty-website#1424
• Make it clear that Eleventy’s data keys can’t be set as computed today 11ty-website#1342
• Suggestion for pagination/"before" documentation: clarify that only js front matter is supported 11ty-website#1334
• Switching between different templating options in the same doc 11ty-website#1230
• Blog post about eleventy folder structure 11ty-website#1657
• Docs aren't organized logically/unclear where to start #3095
• documentation (specific links will be added as they are addressed)
• education (specific links will be added as they are addressed)

Other actionable feedback

• https://mastodon.social/@bamnet/112798502317653396
• https://news.ycombinator.com/item?id=40774613
• https://mastodon.online/@stvfrnzl/112857273496750055
• https://hachyderm.io/@cvennevik/112860045301210656
• https://ethanmarcotte.com/wrote/eleventy/
• https://gkeenan.co/avgb/an-alarmingly-concise-and-very-hinged-summary-of-what-it-was-like-to-build-this-site-from-scratch

[rdela]

One thing I would like to see that I think would be a big, immediate enhancement to the current docs is to have a more MDN style layout, moving our table of “Contents” outline and jump links from the top of the article to a sidebar on the right, if the screen is wide enough, that follows you down the page and highlights the section of your current scroll position. See for example: <details>: The Details disclosure element

Worth noting that Tugboat has this already on the left sidebar via table-of-contents.webc

Our Community page could probably improve by evaluating and incorporating good parts of MDN’s Commuity Page, which links to their Getting started with MDN Web Docs guide to contributing.

To me, the number one beneficial thing we can do in this process is to empower more people to contribute to and participate in documenting the 11ty ecosystem. WebC by itself seems expansive enough to have a whole section of docs, examples, and learning paths. One really long page can feel overwhelming, although it does allow one to use find on page, which can be super helpful to find all occurrences of a term.

Speaking of getting others involved, tagging @riewarden in, I know he had thoughts to share as well! Thank you for collecting and assembling all of this information @d3v1an7! I am looking forward to helping in whatever capacity is best.

[rdela]

More Prior Art

• I like the Recipes on 11ty ♥ WebC by @darthmall
• whose Introduction to WebC also…rocks!
• as does Understanding WebC Features and Concepts by @5t3ph (particularly helped me debugging errors). The rest of 11ty Rocks! is also worth taking stock of, I hear it mentioned frequently as a learning resource.
• Worth mining 11ty Bundle by @bobmonsour, particularly the Getting Started section for learning paths
• same for @nhoizey’s Eleventy tag
• plus @rknightuk’s #Eleventy
• Eleventy Starter Project Updates by @mbarker84
• Going Lean and follow-up 11ty: Index ALL the things! by @LeaVerou, whose “Broken page” issue template link (“Something not working? Report broken page” in right sidebar) might inspire another link on docs pages like our “Edit this page” (which we could potentially make more prominent), maybe “Missing something?”
• Migrating my site from NextJS to Eleventy by @rothsandro
• which mentions Organizing the Eleventy config file by @madrilene
• Nested pagination with 11ty by, wait for it, @d3v1an7

[rdela]

More Slightly Vintage Prior Art from 2020

From Gatsby to Eleventy: Choosing a Static Site Generator for a Personal Site, a precursor to Eleventy Starter Project Updates above also by Michelle Barker, has this passage:

Learning Eleventy

One area where I would say Eleventy is a little lacking is the documentation. It feels slightly harder to navigate than Gatsby’s docs, in that you kind of need to have an idea of what you’re looking for. The Getting Started tutorial assumes a certain level of knowledge, and in that regard it’s not quite as beginner-friendly for someone who might not already be familiar with static site generators.

However, there are a plenty of tutorials around to help you get started:

• Build your own Blog from Scratch using Eleventy by the Filament Group
• Learn Eleventy From Scratch (paid course) – a deep dive that goes beyond Eleventy alone, from Andy Bell
• Beginner's Guide to Eleventy by Tatiana Mac. This is great because it actually explains what a static site generator is, and the pros and cons.

Notably, @Andy-set-studio writes:

The content of [Learn Eleventy From Scratch] was written in May 2020, so parts will be outdated. There’s no immediate plan to do a full update, but this course is now open source, so if you see an issue, please raise an issue.

@tatianamac followed up Part I with Beginner's Guide to Eleventy [Part II], and I’d add to Michelle’s thoughts that the illustrations (in Part I) are fantastic.

Obviously we’d be lucky if any of the people linked and mentioned here got involved in the refresh (refreshment?).

[rknightuk]

I've helped a handful of people in the past few months either switch to, or start from scratch, an 11ty site.

One of the things that they (and I) seemed to find difficult was that there's a lack of first-party tutorials. Yes there are a lot of blog posts from myself and others as mentioned above but those posts can become outdated and maybe don't get people set up in a way that makes sense for them.

A few well-written tutorials that also link out to the specific pages for the technical parts like collections, filters, etc would be very welcome. One for a blog, a marketing site, portfolio, one that pulls in external data to make posts/pages, maybe one that pulls all those concepts together.

I'd certainly be happy to contribute to these.

[riewarden]

Thank you for including me in the thread. I am not a pro web developer, I have an A-Level in Computer Science but never pursued beyond that. I have, however, had success teaching myself and others technical skills, and explaining technical concepts.

During 2020 I taught an amateur theatre group, mostly people over the age of 60 with little computer experience, how to use Zoom to put on a virtual play. I recognised why Zoom's docs at the time were confusing and intimidating for them, and rewrote them for this audience, and they found my interpretation more helpful.

I freelance as a drama teacher, and have also taught non-technical people to make hypertext adventures using Twine, (which I only realised the other day is also a high level static site generator). So I have the mindset of an educator, and work across a variety of learning contexts. I hope my expertise can be helpful.

[rdela]

From @siakaramalegos

• Itsiest, Bitsiest Eleventy Tutorial
  Want to get started with Eleventy but feel overwhelmed? Try out this pared-down tutorial
• 🔖 Eleventy

[d3v1an7]

This is all excellent, thank you @rdela, @riewarden & @rknightuk! As a first step, I've created a shell repo we can start collecting info in, and start forming a bit of a structure: https://github.com/d3v1an7/11ty-docs-refresh

For now, I'd like to keep the focus on structure and content, so it's just folders and markdown for now.

[euro]

I'm in the middle of a handful of sites that are stretched across mostly v2@latest but a few on v3.x

My .02 take is I struggle to find documentation for a particular version (v2@latest vs v3.x) and when I think back on who has had to manage this – I'd say bootstrap does a very good job of locking you into a particular versions' docs.

Build the examples and they will come

Examples are the key to success. Super simple "does one thing only but does it well - (un-opinionated). Straight HTML, non-styled examples of things like eleventyNavigation, Image, etc.

Maybe we should standardize on something like codeSandbox or whatever and link to those simple examples when someone is struggling with one certain thing. I learn better by deconstructing a focused example than by downloading a "starter project" that's so complicated by someone's factoring that I can't follow it. We all think we are "so clever" but it's hurting the community as a whole.

Maybe we need a common taxonomy for examples?

I've often built things when I felt lost with foods. Let's say I want to pull all foods that are green, well you'll get green apples, green beans, green jello, lettuce, jalapenõs, etc.

Lets pull all foods that are red and only fruits: grapes, cherries, etc.

What if I want only foods high in a certain vitamin that's are in season (assuming my data structure supports that) and let's paginate it. Or let's show an example where we do something else with it.

I think this might be an easy to digest set of examples of a fairly complex taxonomy.

Lastly, let's all agree to tone-down the blog examples — we get it - they all do the same thing and I've rarely if ever seen a well done simplified example where I can return a certain author during a specific time period on a particular topic. Some folks work on really complicated IA/taxonomies and we would appreciate guidance and simple-to-understand examples. If the goal is to get some marketshare which translates to stability/longevity/money and I know it's the "indie web" and all but you gotta make some cash and get some adoption in business/.gov if this thing is gonna make it.

I'm super invested in this project and I want it to succeed. Documentation is a big deal and while I'm grateful for what's there I'm excited for what it could be.

[gasatrya]

Hello guys, I just found a good Eleventy documentation so far https://learn-eleventy.pages.dev/ by @uncenter

Repo: https://github.com/uncenter/learn-eleventy

[uncenter]

I've been lurking on this thread for a little while but I guess now is as good a time as ever to pop in! As mentioned by @gasatrya I maintain(ed) an alternative version of https://learneleventyfromscratch.com/ with updated content and resolved several issues with the original (namely my version is actually built using Eleventy!). Never got around to fully completing it (uncenter/learn-eleventy#3) but it was a fun experiment and I would be happy to continue updating it if there is interest!

I brought up a similar thought in one of the issues @d3v1an7 linked earlier (#3095 (comment)), regarding the need for a potential rewrite or at least substantial changes for the documentation. I'd be happy to help with this process and it has been great to see the traction this issue has gained on Mastodon and seeing all the people willing to help! I think I have a pretty unique perspective on this as well, seeing as I am pretty active in the Discord server's help forum (along with a few others) and have seen firsthand what newcomers struggle with.

Lastly, I've also experimented with creating a tool for bootstrapping new Eleventy sites (like https://www.npmjs.com/package/create-astro or https://create.t3.gg/): https://github.com/uncenter/create-eleventy-app. Never got too far with it but would love to see something similar adopted as an official solution! Edit: I've now opened 11ty/create#1 specifically for this matter, following a discussion with Zach on Mastodon.

[JackieGable]

As a noob in Eleventy, I'm delighted to see others taking an interest in refactoring the Docs for Eleventy. I stumbled upon Eleventy when searching for an alternative to Jekyll. Since Jekyll is no longer being maintained, I wanted to try something that has an active community of contributors dedicated to improving it.

After trying 3 times before (in the past 2 years) to transition my website from Jekyll to Eleventy, I finally decided it was time to get serious about it. The Eleventy documentation was the problem for me each time I tried to make the move. Even though it's extensive, it's all-over-the-place and not beginner friendly. So, I began searching YouTube for tutorials on getting started with Eleventy, and I was disappointed. Zach teaches a few but he doesn't approach it from a beginner's point of view.

Once you've moved past the beginner's level in anything, it's hard to think like a beginner again and even harder to teach beginners what you have learned. I'm planning on reaching out to Brad Traversy, (https://www.traversymedia.com) my favorite YouTube teacher, to see if he might be interested in teaching a beginner's course on Eleventy. Brad knows how to explain things in simple terms (teach me like I'm Five) and doesn't assume anything.

I truly believe that more people would learn to use Eleventy if there was better documentation and video tutorials available. Since I am a beginner to Eleventy, I can certainly contribute the documentation that I write for myself once I learn a new concept. Although I'm still struggling with the "collections" concept and how to effectively use it for my websites (I don't bother with blogs) I sort of understand how the collections can be useful for any website that has similar content that can be grouped together.

I plan to follow this thread and see where it goes. Hopefully more people will jump in and help to grow Eleventy and soon it will surpass all the other SSGs.

[rdela]

Thanks @JackieGable for contributing. A search for “Jekyll” on 11ty Bundle may help. Most of the articles are in the Migrating to Eleventy category. I agree they do assume various levels of familiarity with the ecosystem, one of the reasons I agree with Michelle’s take on Tatiana’s Guide.

Here’s another one I forgot earlier:

Eleventy Beginner Tutorial Series
Learn the basics of Eleventy by building a complete site with the help of this six-part series.
by @mneumegen

[rdela]

Two more featured on Docs > More From the Community:

• Getting started with Eleventy by @SeanMcP

  Eleventy has “Get Started” documentation that shows you how to get from a single markdown file to a built site. That is a nice “proof of idea”, but I haven’t found it to be a helpful way to actually get started with Eleventy. This garden aims to be a better guide for building a simple Eleventy site from scratch.

• Curso Eleventy (Spanish video) by @jonmircha

  En este curso te enseño a trabajar con Eleventy, un generador de sitios estáticos rápido, accesible y minimalista.
  📦 RECURSOS:
  🦊 Mis Cursos - https://jonmircha.com/cursos
  🛢️ Repositorio de Códigos en GitHub - https://github.com/jonmircha/starter-project-eleventy-github-pages
  (has accompanying code repo linked above)

It’s interesting to think about entry points to the docs as something that could be improved. In order of discovery, points of first contact, we have:

1. “Eleventy is a simpler static site generator”—An aside: whether or not “simpler” is accurate 😅, I switched to “award-winning open source site generator” on eleventeen, which I got from Zach’s site. I definitely think Eleventy is elegant, powerful, and performant, and in the words of Dan Forsyth, “Elegance is power cloaked in simplicity.” Maybe this emphasis on simplicity instead of, say, elegance and power, makes people feel alienated that they didn’t immediately grasp, and become adept, or even expert at its “simpler” workflow.

2. Below that Homepage Quick Start which links on to Docs, see below, and 6 minutes to Build a Blog from Scratch on YouTube, subtly. Further down on the homepage we get:

   • Sponsors (<sponsors-list>) (maybe better further down the page?)
   • then News from the Blog (useful, could come sooner in my opinion)
   • Why should you use Eleventy? (ditto)
   • then Open Collective Supporters <facepile> (why not next to sponsors? maybe further down the page?)
   • THEN GIANT DOCS BUTTON (literally <giant-docs-button>)
   • then Built With Eleventy (which why not nearer to Why use <logo-cloud> ? Also this and everything below it gets covered by THE GIANT DOCS BUTTON, which while funny is not a great experience)
   • then author <facepile> (maybe further down the page? or on a separate page? facepile overkill?)
   • then Don’t take my word for it 🌈 testimonial quotes
   • then Alternatives
   • and then finally Subscribe to the 11ty Newsletter and the footer links—See Edit Page/Missing something? thoughts above, also thought “Improve these docs” might be good in conjunction with “Missing something?” or on its own—and is Contributor Account still a thing?

3. Docs > Get Started

4. Then kind of a buffet of of Tutorials and Starter Projects leading with Eleventy Base Blog and including some of the ones I added here without referencing this.

5. Then aforementioned More From the Community that two links at the beginning of this comment came from.

6. Then puzzlingly, another Getting Started: with buttons labeled…

   • Command Line Usage
   • Glossary
   • Tutorials
   • Starter Projects
   • Performance
   • Programmatic API
   • Deployment & Hosting
   • Using a CMS

   Feels like this would be more aptly named “Keep Exploring,” “Keep Learning,” “Other Topics,” or similar.

7. Subscribe to the 11ty Newsletter

8. Sponsors

9. Supporters facepile

10. Star Eleventy on GitHub!

11. Footer links

Another interesting thing to think about Jonathan MirCha’s Curso Eleventy brings up is internationalization. Whether 11ty is ready to take that on is the first conversation there I suppose.