search

11ty / eleventy

A simpler site generator. Transforms a directory of templates (of varying types) into HTML.
https://www.11ty.dev/
MIT License
16.84k stars 487 forks source link

11ty documentation refresh #3388

Open d3v1an7 opened 1 month ago

d3v1an7 commented 1 month ago

Why does this ticket exist?

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

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?

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

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 commented 1 month ago

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

Other actionable feedback

rdela commented 1 month ago

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 commented 1 month ago

More Prior Art

rdela commented 1 month ago

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:

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

From @siakaramalegos

d3v1an7 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 (https://github.com/uncenter/learn-eleventy/issues/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 (https://github.com/11ty/eleventy/issues/3095#issuecomment-1803119375), 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 https://github.com/11ty/create/issues/1 specifically for this matter, following a discussion with Zach on Mastodon.

JackieGable commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

Two more featured on Docs > More From the Community:

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:

  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…

    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.

rdela commented 1 month ago

Creating A Blog With Eleventy June 1, 2019 by @JonUK

The code for this article is available on GitHub: https://github.com/JonUK/eleventy-blog

Demo not on Netlify any more, but noticed someone tinkering with Base Blog had also cloned this, so still getting traction in 2024, 5 years later, pretty impressive.

rdela commented 1 month ago

Re: WebC docs Cc: @mirisuzanne @vrugtehagel

($data confused me too fwiw)

From Discord (link)

Is $data documented anywhere?

miriam OP — 08/02/2024 1:38 PM I'm trying to avoid constant data drilling when I just need access to collections inside webC includes - but I can't figure out when $data is available, and what I can expect it to contain. Is there any documentation on it? I think I just saw it in issue comments and started trying to use it.

vrugtehagel — 08/02/2024 1:42 PM As per the WebC codebase:

When isTopLevelComponent is not true (for inner components, not page-level) this scopes:

  • global data under $data
  • helpers under webc.*

This prevents global data leaking into inner components. Notably webc:setup always operates in top level component mode.

I still haven't gotten too deep with WebC, so I don't know the details of it, but perhaps that comment still helps 😄

miriam OP — 08/02/2024 1:48 PM thanks! that helps. I'll play with it more and see if i'm hitting a bug, or creating a bug. 😅

vrugtehagel — 08/02/2024 1:58 PM Well, good luck 😄

urob — 08/02/2024 2:04 PM I wish I had known that earlier -- This had literally taken me hours to figure out through experimentation

Screenshot:

Screenshot 2024-08-04 at 142502

vrugtehagel commented 1 month ago

I'll trow in my thoughts about the documentation as well.

For me, the Eleventy docs are useful for some basic examples for usage, such as the Introducty example *.clowd for an example on .addExtension(). For most of the functions that take configuration, there is a per-option explanation bit at the bottom of the page. I like that.

There are a few things I struggle with personally. For one, the search function often does not understand my search term adequately. For example, when I'm looking for addTransform, I want to find the Transforms page that document this feature; instead, that page is ranked 103rd in the search results and most results are just matching the add part.

Open to see the current search results for addTransform image

For a lot of the more complex questions I have, I find myself going to the source code on GitHub for the answer more than the documentation. In one way, that's a compliment to the codebase for being readable, but on the other hand, that indicates an issue with the documentation.

One thing I'd like to add is that I do very much appreciate the handcraftedness and the amount of text we get in the current docs. For an example on docs I dislike: here's useCssVar() from vueuse. There's basically no text, with only examples in code and some type declarations (not even outlining the parameters). At least Eleventy's docs feel far more like it wants to help you and explain things to you; I think this is an important aspect that should be kept in a potential rewrite.

siakaramalegos commented 1 month ago

Hey folks, I'm an admin in the discord - would you like a channel dedicated to the docs refresh project? Just let me know. Zach isn't really in the Discord, but if it's primarily you all working on it and it would be helpful to you, then I'm happy to create it.

uncenter commented 1 month ago

That would be amazing! GitHub issues feel a bit slow for this kind of collaboration :)

siakaramalegos commented 1 month ago

Done! It's the new docs-refresh channel

On Tue, Aug 6, 2024, 12:43 PM uncenter @.***> wrote:

That would be amazing! GitHub issues feel a bit slow for this kind of collaboration :)

— Reply to this email directly, view it on GitHub https://github.com/11ty/eleventy/issues/3388#issuecomment-2271712806, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABEOLMKMQFZYISURWEACHHTZQD4LFAVCNFSM6AAAAABLTKICKKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDENZRG4YTEOBQGY . You are receiving this because you were mentioned.Message ID: @.***>