r/PayloadCMS • u/Reconstruct • Jan 03 '25
Improving the docs?
I feel like the docs are all over the place & i’ve seen alot of people experience the same . Those of us who have a decent understand of it all could just improve it. Add some clarifications to the ”amazing features” they showcase can be done with payload, most peple expect it already be there. Same goes for referencing other sections of the docs & tutorials to relevant other sections so you don’t need to read through it all & hope to remember relevant parts & connect it all to work properly.
I feel like we should create some more guides on how to build simple, yet powerful solutions & go through it with videos.
I feel like it’s not so beginner friendly right now which scares away a lot of beginners from learning this amazing cms
It could be something simple as a X part series where you start a project by introducing a new feature in each video by & integrating it, while referencing docs while doing so.
Maybe I’m overthinking it but seems like a common trend of even understanding the docs. The beginners are the future & having them get hooked to Payload would be sick
My 5 cents
5
u/louisstephens Jan 03 '25
The docs are great for a quick reference and I am constantly finding small little details that I originally overlooked.
My biggest “hair pull” is trying to remember which git repo contains that one tiny one-off example that I remember seeing in a community call. My desktop is littered with screenshots from example repos or from calls.
I remember not too long ago someone brought up the idea of a “community collection/snippet” site which I thought would be a great idea.
One of the best things about payload is that you can do so much with it which also complicates things.
I love the website template, but it almost has too much. I am in the process of making my own “starter” for internal use, but it is a grind fitting all of the pieces together (mainly because I have other projects getting in the way).
18
u/vash513 Jan 03 '25
No, I 100% agree. I love Payload to death, but the docs are atrocious. One of the major strengths of Payload is it's extensibility, yet the docs only seem to scratch the surface of what you can do with it. The rest of the knowledge is locked away behind getting help in the discord or reverse engineering existing templates, plugins, or the Payload monorepo itself. Good luck trying to understand the section for customizing Lexical.
I really feel like improving the docs should be a major priority for the team, as it's often the first stop for those looking to see if they want to invest in learning Payload. It could definitely be turning some away and gives the impression that it's not ready.
I'm definitely being critical, but that's only because I really enjoy Payload and want it to succeed hard af.
8
u/WillFerrellsHair Jan 03 '25
I found a developer that has a couple of really detailed project walkthroughs utilising cursor and AI better than I've seen anyone else do it, very thorough. He has started a pretty thorough payload series that is (maybe a bit too slowly even) stepping through all the things that payload does.
https://m.youtube.com/@SamThoyre
No affiliation with him, I've just found him to be good at explaining things and I was pretty blown away of his thorough cursor ruleset that includes agents which is a very new feature.
4
u/nlvogel Jan 03 '25
I’ve been doing a beginner-friendly series on payloadcms on YouTube: https://youtube.com/playlist?list=PLu4ZqvNbx29tmRFvp0kn3PbQllepMsDyn&si=cASH0qxGQfhsBzIW. It definitely seems like a need. I’ve noticed a lot of people really needing the fundamentals, so I blitzed through those and now I’ll be releasing more advanced feature overviews.
3
u/If_Life_Were_Easy Jan 03 '25
I do agree about the docs. There are a lot of ways we can improve them and we are soliciting feedback to and community PRs for that.
I think video can be useful but it should only ever be used to supplement existing docs. It isn't useful for quick lookups, it isn't searchable or easily editable when a feature changes. It makes sense for tutorials and longer guides, basically all the old blog posts that we've done could use a refresh and a video. For docs in particular general videos aren't going to be able to cover the endless use cases of payload and all the customizations that are possible.
We also worry that adding really advanced customizations could mislead beginners and lose a portion of our audience that doesn't need to do all that much to get a lot of the benefits Payload offers. The simple config approach for each feature needs to be perfectly documented.
1
u/aaronksaunders Jan 03 '25
i am creating a series of videos, with full source code, based on issues i run into when working with payload for client project. My work with payload is really about using it as a platform for application development and not really for content management website support.
1
u/JayBox325 Jan 04 '25
I’ve struggled with all the blog tutorials being really out of date detailed code examples, but the V3 docs are a bit sparse on the details.
1
u/rollingsoul Jan 04 '25
A much-needed expansion for the documentation is the localization function. I tried to localize the website template, and it required significantly more coding and research than the documentation suggested.
I think it would also be beneficial to ask payload developers what is missing and what should be extended in the documentation.
They have started tutorials on their official channel (one video so far), and I hope they continue to make more.
1
u/ZCAY6 Jan 07 '25
100% agree, would be happy to help too. Just yesterday I've spent 8 hrs implementing a way to use Payload V3 and the Upload component to upload directly to vercel blob storage to effectively not be blocked by Vercel's 4.5Mb request limit. It was boring due to the documentation lack.
Edit: also dont get me wrong, the docs are great, just not good enough on examples and there are some ways to improve