11ty documentation refresh #3388
Comments
|
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. |
More Prior Art
|
More Slightly Vintage Prior Art from 2020From 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:
Notably, @Andy-set-studio writes:
@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?). |
|
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. |
|
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. |
From @siakaramalegos
|
|
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. |
|
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 comeExamples 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. |
|
Hello guys, I just found a good Eleventy documentation so far https://learn-eleventy.pages.dev/ by @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. |
|
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. |
|
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 |
|
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:
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. |
contributors: - uncenter - JackieGable - rdela authors: - mneumegen - jonmircha from 11ty/eleventy#3388
|
Creating A Blog With Eleventy
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. |
|
Re: WebC docs ($data confused me too fwiw) From Discord (link) Is $data documented anywhere?
Screenshot:
|
|
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 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 Open to see the current search results for
|
|
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. |
|
That would be amazing! GitHub issues feel a bit slow for this kind of collaboration :) |
|
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
<#3388 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/ABEOLMKMQFZYISURWEACHHTZQD4LFAVCNFSM6AAAAABLTKICKKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDENZRG4YTEOBQGY>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
|
I was wondering, whether we could have code examples written in Eleventy and embedded in the page instead of hosting it on Stackblitz, Codepen or similar. In fact, I noticed on CSS Tricks that certain embedded Pens are dead, which render the pages shallow 😿 Could we build something similar? Initially we had two user groups identified. I could imagine we have three.
For 1. we should have multi-medial guides. That is, How Tos, Cookbook Receipts, YouTube videos, Courses etc. The target is to explain how to get started. I would argue, by migrating from an existing Static Site Generator (Jekyll is dead? 🙀 ) or Content Management System (looking at you, WordPress). For 2. it would be „okay, I have my content, how do I make it my own?”. That would involve tweaking and optimising it. I think about how to use the Data Cascade here, talk to APIs, Good Practices on writing templates etc. For 3. it is about the code annotations. JSDoc, TypeScript definitions, running it in Docker, Containers etc. I feel like this would be a CONTRIBUTING.md. Does this sound senstive? I'm ramping up my activity on GitHub slightly (sparked by contributions to other projects that scratched an itch) and would like to see whether I could lend a hand here or there again. |
|
Great ideas there. For the interactive examples, that'll be difficult to implement, but potentially possible. We'll need a browser-compatible implementation for a file system and for all Eleventy's Node-specific dependencies, and it might not be the most light-weight, but it's certainly something to look into as I do believe it would add a lot of value. For the target audiences for the documentation; yes, you are right about contributers, but this should not be part of the documentation and therefore are not within the scope of this issue. But you're welcome to open another issue for this 😉 Your suggestions for newcomers are great, but don't all have to come from the official website. For example, anyone can make 11ty tutorials on YouTube and this would be a great step forward regardless of who makes them. And people have already been creating resources; for example 11tybundle.dev. The goal with the documentation refresh is (or at least, I think, should be) to structure the documentation better and have an official reference for people to either get started with, or dive into the nitty-gritty of Eleventy. Lastly, and I don't mean to discourage you, but this documentation refresh thing is not the fastest moving project, so if you're itching to get your hands dirty, your experience could disappoint. |
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
Out of scope
addTemplateFormatsAPI 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.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!
The text was updated successfully, but these errors were encountered: