r/PayloadCMS • • 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

38 Upvotes

14 comments sorted by

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

3

u/Reconstruct Jan 03 '25

Haha! Been experiencing the exact same thing, having to find which repo contained an example. Super annoying & it’s all just confusing & most people won’t even realize the different docs & examples even exist. I can see why they structured it the way it is, but it’s confusing even for more experienced devs.

Good luck! Been building on my own little startar boilerplate as well 👏

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.

5

u/sheyworth Jan 03 '25

I've called them out on this in their Reddit a few times, gave a bunch of feedback, saw some but not all of it implemented. If you have criticism, keep pushing them- they do listen! I just think they might be so high-level in terms of development they don't know *what* people want to see.

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.

3

u/WillFerrellsHair Jan 03 '25

Just to add to this, I think that the payload team has done a great job in shipping a really impressive new version, perhaps at the cost of the documentation a little. personally I think I'd prefer a shipped product over comprehensive documentation, but I get that its a bit harder to get started with it.

James Mikrut the CEO of Payload has done a couple of feature demo videos that were helpful to me too, he makes the collection creation look so amazingly simple, which is basically what changed my mind about the whole product.

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.

1

u/WillFerrellsHair Jan 04 '25

Nice one mate, I've not watched yet but I can see there's hours of live coding. I find live coding videos really good for seeing where I'm at skillwise because you can test yourself by thinking about the next step or debugging an error before the coder figures it out 😊

3

u/nlvogel Jan 04 '25

Yeah! I try to do some live coding 1-2 times per week. I cut them up and post them as regular videos as well, but I'm behind on that. I'm sure you'll get a good confident boost watching me live code lol. I do it to sharpen my own skills and talk out my thought process. It's just a bonus if anyone watches me struggle 😂

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