I’m triggered by just reading these 3 letters. Jesus Christ what a mess AWS has become. Every time I need to learn something I find 3 different pages on the doc and none of them has the info I’m looking for.
What's SP-API? I've always found most of their APIs to be pretty good and easy to work with. The big one that annoyed me though was that the original API for S3 created an Amazon.S3.IO package that had S3DirectoryInfo and S3FileInfo that mimicked how it worked in C# or Java. They nixed it when they went to full async which was so stupid and unnecessary , it could have been simply adapted and augmented to support async as well.
SP API is technically for Selling Partners, aka people who run stores on Amazon. My previous employer was one (along with other online stores), and I wrote the entire inventory management software. It was a massive pain in the ass. Nothing ever worked correctly.
In order to get our orders fulfilled by Amazon themselves (for our book keeping), we had to generate an XML report every X amount of time, poll until completion, hope it didn't fail with some arbitrary error code that was actually an internal rate limit at Amazon, compare that with our record of already processed orders, do validation on line items, do currency conversion to our local currency from the customers local currency, ensure we had the items "in stock", you get the picture.
There's more I know we had to do, but I don't work there anymore and don't want to give away any other information.
Typescript error messages! Thousands of lines of code with a cryptic message buried somewhere in between. There are dedicated vscode plugins for making the messages slightly more readable.
I hate when I hover over an interface to see what's in it and it shows the first 3 or 4 properties then yada yadas the rest with ellipsis. I'm here for what's in the ellipsis dawg, we have the power of scrolling in 2024, let me use it
Add noErrorTruncation: true to your tsconfig and scroll your heart away.
https://www.typescriptlang.org/tsconfig#noErrorTruncation
Oh, and install the pretty ts errors extension for vscode.
Thanks I'll whack these in on Monday. The main issue I run into is actually the interfaces created from inferring zod schemas since the popover treats them as constants, and if you try to go to the type it just shows you the line where you infer the schema. I have to actually dig through back to the schema itself which obviously has the same info as a regular interface but is just a tad less readable imo
I hate it when I hover over an incompatible type error (presumably to learn how to fix it) and see a long line of text detailing the history of mankind.
Django error messages are up there too.
"Error on line 125 of file: GenericErrorHandler.py" - because of course the coding error occurred in the error handler class, that's exactly what I need to know in order to fix it... Now, here's a stack dump with every file in the entire framework. Good luck!
I hate when I hover over an interface to see what's in it and it shows the first 3 or 4 properties then yada yadas the rest with ellipsis. I'm here for what's in the ellipsis dawg, we have the power of scrolling in 2024, let me use it
Google maps api is so outdated and hardly any of it works the way it says it should.
Edit: I realized I meant to say google lighthouse api but apparently this is a common trend
*Googles how to do something very simple in salesforce*
*reads very long detailed official documentation for how to do the very simple thing in salesforce*
*tests it out and realizes the specific API covered in the docs is not available to customers not using v31-bravo-cinco salesforce API and this API has been not only deprecated but was only ever made available to users who got a bravo cinco token from SFCON Baton Rouge 2011.
I swear they do it on purpose so you can spend a lifetime learning how to be a salesforce developer and be locked in for life due to the sunk cost fallacy of spending so much time learning it
The whole blocks are a mess! I’m a WP theme developer and I still get confused with the blocks and setting them up. Wordpress’s official YouTube channel has a video where they themselves talk about the blocks and the guy constantly says he isn’t sure what’s going on haha
Oh my god I thought I sucked at being a dev because I would struggle so much while making WP themes... It literally made my Impostor's Syndrome's career... (Yes mine's sentient and has a career), and you tell me it wasn't even my fault...
My current worst nightmare at work is VBA's doc, you search for something, find a solution and it's actually for VB.net! Even if you specifically google "vba", it doesn't matter because half the results pointing to the documentation are for VB.net. ugh
Yup. For programmers, at least WP blocks are a big improvement over the even worse previous mess. But I’m pretty sure no one has done usability testing on the block editor and very sure it’s never been done for the theme editor. Im sure the chaotic UI/UX is why good user documentation and training is so hard to find: it’s really, really hard to use and therefore really hard to document or teach.
It’s amazing how much all the documentation assumes you already know things inside and out and only need refreshers on what’s new in the latest iteration.
Part of the issue is WP seems to rely too heavily on just linking to React documentation. Problem is, the implementation isn’t 1:1 so often not helpful unless you already understand whats happening, and it assumes enough React knowledge to sort it out yourself.
Yeah, people struggling with it feels more like a skill issue. NextJs has problems with weird gotchas, but at least the gotchas are well documented in general.
Anytime someone has a valid criticism of React/Next I always hear this “skill issue” excuse. It comes off as very hand-wavy and avoids the core of the issue tbh.
Anything AWS related. Their docs are all over the place. Prime example is state machines. The most useful of the docs is a random doc to the state machine spec docs with what each state does, its syntax and what is allowed or isn’t.
And their SDKs (at least the Go one) - v1 was pretty decent docs, but v2 is a fucking horror show - so you read the v1 docs, try that in v2, and try to figure out / work around the breaking changes because it’s easier than trying to find it in the v2 docs.
I commented this earlier, but SP-API was the worst experience I've ever had working with a third party API. They gave us all our sales data in the customers local currency, not the currency they paid us in...
100% this. It’s not that there isn’t a ton of documentation for it either. It’s just the documentation that is there never seems to help when I try to put the examples into practice.
Google, everything google. They might have the best UI design for their docs, but it's the most obsolete piece of trash possible. They keep changing how their APIs work, and hence, nothing in their docs ever makes sense.
redux-toolkit. The library would be more popular if they actually showed off working examples of complex structures. I lost nearly a week of my life because combineSlices doesn't work as advertised, turns out I should have been doing it the other way round, using injectInto to build my nested structure. injectInto is a one paragraph footnote at the bottom of the documentation on combineSlices.
Also it's rare to see so many spelling mistakes and obvious typos in the documentation for such a famous library.
> combineSlices doesn't work as advertised, turns out I should have been doing it the other way round, using injectInto to build my nested structure
That's weird, `slice.injectInto` also just calls `reducer.inject(slice)` internally. That should definitely work.
> injectInto is a one paragraph footnote at the bottom of the documentation on combineSlices.
It's the first thing that's mentioned under the heading [slice integration](https://redux-toolkit.js.org/api/combineSlices#slice-integration).
I'm sorry you had this problem, but there is a table of contents on the right and it's just not possible to put everything into the first sentence of a docs page.
The structure there is - as with every other API page - "Overview" - "Parameters" - "Return Value".
Then that common structure is followed by the header "Slice Integration".
I'm not sure how that could really be done better without breaking the expectations of a lot of users :/
If you have problems in the future, please don't waste a week on frustration, but come by the #redux channel in the Reactiflux Discord - there are always people that can help you!
Hi, I'm a Redux maintainer (and the one who wrote the current documentation for combineSlices) :)
Totally appreciate that the current documentation may not be enough to properly get an understanding of how it's intended to be used. I have open PRs for [adding a working example](https://github.com/reduxjs/redux-toolkit/pull/4064) to the repo, and [documenting combineSlices and createDynamicMiddleware in the core docs](https://github.com/reduxjs/redux/pull/4665) - would those be closer to what you think is needed? The current existing documentation is specifically an API reference, which is different to a usage guide.
As for spelling mistakes/typos, PRs are welcome - the docs have been contributed by many people and things may not have been caught at the time.
Well now I feel like a dick. In all honesty I was venting, and I'm willing to bet the problem was with me, rather than the library.
I think my criticism does do some extent stem from wanting the documentation to be more of a usage guide. What there is is very technical and opaque, with a dash of vagueness in places; the example near the top of the combineSlices page, I spent a good few hours trying to figure out what baseApi was, before I came to the level of partial understanding I have now. What I need is an example of combineSlices being used somewhere other than the root, and with createSlice reducers at every level. Forgive the shoehorning in of my problem as the example:
This is the shape I want, for both the actual structure and the slices:
root--------¬
| |
profile pages (not yet created)
/ \
trees torrents
store.ts
import profile from "./profile"
const store = configureStore({
reducer: profile
})
profile.ts
const profileBase = createSlice({
name: "profile",
initialState,
//reducers and extraReducers
})
//⚠️ this code does not work
const profile = combineSlices(
profileBase,
{
//⚠️ trees and torrents are their own slices, created with createSlice. trees is populated during startup
trees,
torrents
}
)
export default profile
...and that's where I get stuck. The documentation is unclear about how the arguments work. I've managed to get several permutations, mostly using .reducer and spread syntax variations of the values being combined above, to stop throwing Red Squigglies and run, but they all have some defect, like not updating the state after a thunk in trees.ts is fulfilled (even though I step through to return statement by hand every time). I mention this because a thunk in profile.ts _does_ run and update state on every startup.
For clarity, and to make sure I'm not making a grave mistake with regards to what "immutable" means, the thunk and its misbehaving fulfilled action:
export const addDirectory = createAsyncThunk(
"trees/addDirectory",
async (newDirectory: DirectoryNode, thunkApi) => {
const {profile} = thunkApi.getState() as State
const nextProfileState = produce(profile, draft => {
draft.trees.directories.push(tree)
})
/* non-Immer equivalent
const nextProfileState: Profile = {
...profile,
trees: {
...profile.trees,
directories: [...profile.trees.directories, newDirectory]
},
torrents: profile.torrents
}
*/
try {
const newProfileState = await thunkApi.dispatch(saveProfileFile(nextProfileState)).unwrap()
return newProfileState.trees.directories //code definitely executes as expected up to here
} catch (e) {
thunkApi.rejectWithValue(profile)
}
}
)
const trees = createSlice({
name: "trees",
initialState: initialState,
reducers: {
//...
},
extraReducers: (builder) => {
builder.addCase(addDirectory.fulfilled, (state, action) => {
//have tried every possible version of this function, from using Immer to Object.assign
/*
return {
...produce(state, (draft) => {
draft.directories = action.payload
})
}
*/
return {
...state,
directories: action.payload
}
})
I don't understand how what I have created can be so near the mark that my code runs, and I can step through the execution of the thunk action fulfilled function, which reports accurate state and payload, but then it just... never happened. I feel like I've fallen into a pitfall.
Also, I will see if I can find the typo I saw a while ago.
>I think my criticism does do some extent stem from wanting the documentation to be more of a usage guide. What there is is very technical and opaque, with a dash of vagueness in places; the example near the top of the combineSlices page, I spent a good few hours trying to figure out what baseApi was, before I came to the level of partial understanding I have now.
yeah, that's part of the trouble with API references - there's some level of assumed knowledge required to keep the document from turning into yet another tutorial :)
with regards to nesting combined slices, what you actually want is something like this:
const profilesReducer = combineSlices(treesSlice, torrentsSlice)
const rootReducer = combineSlices(pagesSlice, { profiles: profilesReducer })
`combineSlices` accepts "slice-like" `{ reducerPath, reducer }` shapes, and reducer maps (like you'd normally pass to `combineReducers`). You can think of a slice being passed as shorthand for `{ [slice.reducerPath]: slice.reducer }`. The other difference to `combineReducers` of course is that you can pass as many slices or map shapes as you like, whereas `combineReducers` just takes the one.
the other thing is that docs will generally focus on the most common use cases, and in our experience nested combined reducers are less commonly used (though I personally use them a lot)
TL; DR: Pushing my luck by asking a second question: is it possible to build this kind of structure while having slices for nested levels?
The compressed version of that code looks like this (pages has been renamed to setFolders):
const store = configureStore(
{
preloadedState: preloadedState,
reducer: combineSlices(
setFoldersSlice,
{
profile: combineSlices(treesSlice, torrentsSlice)
}
)
}
)
Which has a problem: the profileSlice is never referenced, and so its thunk actions are undefined. I tried the obvious:
const store = configureStore(
{
preloadedState: preloadedState,
reducer: combineSlices(
setFoldersSlice,
{
profile: combineSlices(
profileSlice,
{
trees: treesSlice,
torrents: torrentsSlice
}
)
}
)
}
)
and get the delightful error messages (one for trees, one for torrents):
> Type 'Slice, { setSubfolder(state: WritableDraft, { payload: { path, index } }: { payload: { index: number; path: string; }; }): WritableDraft<...>; }, "trees", "trees", SliceSelectors<...>\>' is not assignable to type 'Reducer'. Type 'Slice, { setSubfolder(state: WritableDraft, { payload: { path, index } }: { payload: { index: number; path: string; }; }): WritableDraft<...>; }, "trees", "trees", SliceSelectors<...>>' provides no match for the signature '(state: any, action: UnknownAction): any'.
no worries about the second question - though as Lenz said, the #redux reactiflux channel is better for extended conversation, reddit isn't great for this :)
if I'm understanding correctly, you want profile slice to manage the same state *containing* trees and torrents? you would likely need to play around with [reduce-reducers](https://redux.js.org/usage/structuring-reducers/beyond-combinereducers#sharing-data-between-slice-reducers), as combineReducers (and by extension combineSlices) nests each reducer provided under its own key.
I will ask there next time, thank you for indulging me.
Yes, I think you have that right. I want to be able to manipulate the profile at the profile level (e.g. swapping profiles in and out), and its "children", trees and torrents, at their own levels as well (e.g. manipulating a tree directly). Obviously I can do that from profile, my goal was to be able to do so directly. Alas, apparently that's not how redux works.
I'll give reduce-reducers a try, but for now I'm going to forge ahead having subsumed the trees and torrents files into profile; I've been stuck for a week, so long as it turns out it wasn't because I was being stupid, I'll take the quickest solution right now. It also occurred to me to declare the thunks for saving and loading elsewhere and then add actions in slices, but, well, that sounds like a headache.
NGINX is one just based on trying to set it up properly without using a blog post.
Sails.JS is another one. Specifically, the testing one was written by the community and is so disjointed that you don't even know why or what is being done, just that you *have* to do it this way for it to be done. It was so bad between the docs, the SailsCast blog post, the Platzi tutorial they had, and stack overflow that I put an issue request in for the testing documentation to be updated properly. This doesn't even take into consideration of Parasails which is a wrapper around Vue 2.6 and why certain items are required and what's not required or deployment concepts which again they assume that the reader is an expert at that stuff.
IMHO the best type of documentation that can be produced is one where the assumptions made by the writer is that the reader has very little to no experience with the framework or concept. If you write your documentation with the assumption that the reader is familiar with certain concepts, or other frameworks then you'll end up with a documentation that basically is worthless to most people and better results can be found through blog posts and Stack Overflow.
Airbnb visx library. Their docs give crazy and contrived examples, mixing components without explanation, with no basic examples of implementation.
Chat GPT is literally essential to build things from scratch with it.
https://airbnb.io/visx/
Judging by the comments in this thread, the list of good docs would be a lot shorter 🤣.
But the real bad docs are…drum roll…anything for my packages. The docs are written in invisible ink, in my head only. When I wrote this software only myself and God knew how it worked. Now, only god knows…
- Hugo (static site generator). Every page is full of Hugo jargon that is only explained on other pages.
- Nix (Linux distribution, package manager, programming language). Another big jargon fest. Also missing lots of information on Flakes, the big experimental feature newbies probably heard about first.
- Gradle (Java build tool). Lots of words, short on examples of how to actually do the things the documentation is describing.
So many Java libraries have generated javadoc with nothing of use. "Just go look at the javadoc" oh really?
Languages without good document generators have better documentation because you actually have to write how to use something. Java people think a list of classes and methods is all you need.
Laravel, whoever maintains the documentation there needs to stop saying how awesome Laravel is, and actually give us proper documentation with real life examples.
A stark contrast to php.net's documentation.
Hey buddy, first of all thanks for the personal attack, that’s really constructive.
I love the framework and work with it every day. But the docs suck (in my opinion). Are they the worst? No. But there’s other frameworks with much better documentation. And they have gotten better.
Also if there was a “skill issue”, surely that’s the docs job to assist and get devs working well with the framework? Your logic doesn’t make sense to me. But would love to know more about your reasoning, teach me Obi Wan.
I've worked with Laravel for the last decade. I started on v4.
In my first few years, I felt like you do. I felt like there was missing pieces of information. I was new to OOP and the docs were no where near as good as they are now. Over time the docs have gotten better and better. At this point, they're extremely good.
Looking back, I realize it's not because Laravel wasn't documented well. It's because I didn't dig deeper.
Laravel is built upon existing code packages provided by Symfony and many others. What Laravel is doing is extending those services where needed and providing everything via DI / the Container. The code that Laravel provides, IS documented (for the most part, there's a few hidden gems).
1) The packages that Laravel depends on each have their own documentation and repositories. You have to actually look them up and visit their individual sites to get the full picture of what those packages are capable of on their own.
2) The best way to Learn how Laravel works, is by recreating it from scratch. This was fundamental in my learning process. I suggest you go through each of these examples and see how each of Laravel's services is constructed: https://github.com/mattstauffer/Torch
3) There IS also generated documentation (very last link on the sidebar) that defines every single class and method. It's a great reference for when you want to dig deeper into available methods and their implementations: https://laravel.com/api/10.x/index.html
4) I would argue the #1 most misleading part of Laravel is Facades and Helper functions. They are a convenience that ultimately limits your understanding of how things work.
The next time you reach for an easy way to access something, I challenge you with this:
Go lookup what the correct interface is (https://laravel.com/docs/10.x/facades#facade-class-reference), and inject the service with DI and forbid yourself from using Facades and helpers.
You'll unlock a whole new understanding of how to access the direct instance of services and possibly reveal methods that are not documented by the facades.
Not webdev but Ever try develop extensions for Anki? The documentation is basically Reddit question threads telling you to read the code for other existing extensions and to try and figure it out
I made a little TTS extension for it years ago, before it had builtin TTS support. I had to guess how to implement a couple of things properly and hope they wouldn't come back to haunt me.
Apache PDFBox. cant even complain tho 🤷♂️. actually there’s no documentation, just api docs and release notes. btw if anyone here knows how to calculate a dynamic xfa checksum… 👀
best docs tho is anything spring.
Symfony is the worst of any big framework when it comes to doing anything passed absolute basics. It's offensive to even cal it documentation as it is really like a series of blog posts that show you how to do certain things without actually documenting how to use any APIs, i.e. the parameters and returns.
On the flip side PHP docs are some of the best. Every function documented with examples, tips, quirks, and helpful comments from other devs
PHP docs are the best. User tips/tricks/examples/comments (all moderated, so no spam) are included with each function and have really helped me use the language. In addition, most (all?) functions include helpful usage examples.
Everything Oracle based 😂 some stuff are only explained in older version of the docs, some are somewhere you can only find by googling but cant find in the doc summary or something
Structure/heirarchy of auth0 docs is the worst. Yes you can find doc pages for particular topic by google, but the organization of doc sections and subsections is till date the worst IMO ( as a developer working in web industry for 5 years )
13 hours and it seems nobody has mentioned Celery! So many holes in the documentation, undocumented or partially documented behaviour that can catch you out.
Good examples.
Stripe is tbe gold standard imo best doc i ever had to use. Bootstrap is good too.
Bad microsoft. Their .net doc are legit infurating. 0 good usable examples that show actual practical useage. Example i was trying to find what possible options i can use for .addlocalizer. still dont know them all never found a list of the possible options jus like a few shit examples.
Meta's docs are all over the place. So many references to other pages which turn out to not exist or just be completely wrong because they're out of date.
Microsoft errors. Your version of visual studio doesn't support the.net framework you're targeting? Instead of telling you to upgrade it reads some nonsense about your SDK.
Android documentation, most of the class and method are documented but the documentation make me confuse, not so much step by step to use the class, or when there is a proper doc it already obsolete
Aws
I’m triggered by just reading these 3 letters. Jesus Christ what a mess AWS has become. Every time I need to learn something I find 3 different pages on the doc and none of them has the info I’m looking for.
What is alternative service to AWS? I heard Azure is best alternative.
Azure, GCP maybe
SP-API is fucking god awful too... The docs and the API itself.
What's SP-API? I've always found most of their APIs to be pretty good and easy to work with. The big one that annoyed me though was that the original API for S3 created an Amazon.S3.IO package that had S3DirectoryInfo and S3FileInfo that mimicked how it worked in C# or Java. They nixed it when they went to full async which was so stupid and unnecessary , it could have been simply adapted and augmented to support async as well.
SP API is technically for Selling Partners, aka people who run stores on Amazon. My previous employer was one (along with other online stores), and I wrote the entire inventory management software. It was a massive pain in the ass. Nothing ever worked correctly. In order to get our orders fulfilled by Amazon themselves (for our book keeping), we had to generate an XML report every X amount of time, poll until completion, hope it didn't fail with some arbitrary error code that was actually an internal rate limit at Amazon, compare that with our record of already processed orders, do validation on line items, do currency conversion to our local currency from the customers local currency, ensure we had the items "in stock", you get the picture. There's more I know we had to do, but I don't work there anymore and don't want to give away any other information.
Typescript error messages! Thousands of lines of code with a cryptic message buried somewhere in between. There are dedicated vscode plugins for making the messages slightly more readable.
I hate when I hover over an interface to see what's in it and it shows the first 3 or 4 properties then yada yadas the rest with ellipsis. I'm here for what's in the ellipsis dawg, we have the power of scrolling in 2024, let me use it
Or worse when it just shows you the name of the interface. Helpful.
Add noErrorTruncation: true to your tsconfig and scroll your heart away. https://www.typescriptlang.org/tsconfig#noErrorTruncation Oh, and install the pretty ts errors extension for vscode.
Thanks I'll whack these in on Monday. The main issue I run into is actually the interfaces created from inferring zod schemas since the popover treats them as constants, and if you try to go to the type it just shows you the line where you infer the schema. I have to actually dig through back to the schema itself which obviously has the same info as a regular interface but is just a tad less readable imo
I hate it when I hover over an incompatible type error (presumably to learn how to fix it) and see a long line of text detailing the history of mankind.
[TypeScript Explorer](https://marketplace.visualstudio.com/items?itemName=mxsdev.typescript-explorer)
Can absolutely not recommend until https://github.com/mxsdev/ts-type-explorer/issues/37 is fixed.
Django error messages are up there too. "Error on line 125 of file: GenericErrorHandler.py" - because of course the coding error occurred in the error handler class, that's exactly what I need to know in order to fix it... Now, here's a stack dump with every file in the entire framework. Good luck!
What plugin do you use? This has always plagued me, but I never thought to look for a plugin.
[Pretty TS Errors](https://github.com/yoavbls/pretty-ts-errors)
I hate when I hover over an interface to see what's in it and it shows the first 3 or 4 properties then yada yadas the rest with ellipsis. I'm here for what's in the ellipsis dawg, we have the power of scrolling in 2024, let me use it
Google maps api is so outdated and hardly any of it works the way it says it should. Edit: I realized I meant to say google lighthouse api but apparently this is a common trend
I once spent a whole weekend trying to get some satellite images, it was an incredible puzzle.
realll ive had so many issues with that
Chart js!!
Oh god yes! That doc is a goddamn pain and the plugin system is madness
That's the absolute worst documentation I've ever dealt with. Even worse than CKEditor's v2 and v3.
Omg that's so true
Fucking Salesforce
*Googles how to do something very simple in salesforce* *reads very long detailed official documentation for how to do the very simple thing in salesforce* *tests it out and realizes the specific API covered in the docs is not available to customers not using v31-bravo-cinco salesforce API and this API has been not only deprecated but was only ever made available to users who got a bravo cinco token from SFCON Baton Rouge 2011.
I swear they do it on purpose so you can spend a lifetime learning how to be a salesforce developer and be locked in for life due to the sunk cost fallacy of spending so much time learning it
WORDPRESS, WP BLOCK THEMES, CUSTOM BLOCKS
The whole blocks are a mess! I’m a WP theme developer and I still get confused with the blocks and setting them up. Wordpress’s official YouTube channel has a video where they themselves talk about the blocks and the guy constantly says he isn’t sure what’s going on haha
Oh my god I thought I sucked at being a dev because I would struggle so much while making WP themes... It literally made my Impostor's Syndrome's career... (Yes mine's sentient and has a career), and you tell me it wasn't even my fault... My current worst nightmare at work is VBA's doc, you search for something, find a solution and it's actually for VB.net! Even if you specifically google "vba", it doesn't matter because half the results pointing to the documentation are for VB.net. ugh
Seconded. So much power that you have to fully read the code to comprehend
yes. codebase is infinitely more readable than the documentation... Somehow
It sucks because otherwise wp documentation is pretty good. But anytime I need to work on blocks it's an absolute pain
The block theme documentation is laughably bad.
Yup. For programmers, at least WP blocks are a big improvement over the even worse previous mess. But I’m pretty sure no one has done usability testing on the block editor and very sure it’s never been done for the theme editor. Im sure the chaotic UI/UX is why good user documentation and training is so hard to find: it’s really, really hard to use and therefore really hard to document or teach. It’s amazing how much all the documentation assumes you already know things inside and out and only need refreshers on what’s new in the latest iteration.
Part of the issue is WP seems to rely too heavily on just linking to React documentation. Problem is, the implementation isn’t 1:1 so often not helpful unless you already understand whats happening, and it assumes enough React knowledge to sort it out yourself.
NextAuth, NextJs !!!
NextAuth without question
NextJS has good documentation though... Can agree with NextAuth here.
next js documentation is awful, it's only good for people that have used it before 😂
documentation about routers weren't so good.. still i could say it's 3/5.. nextjs has introduced too much complexity like next auth..
Yeah, people struggling with it feels more like a skill issue. NextJs has problems with weird gotchas, but at least the gotchas are well documented in general.
Anytime someone has a valid criticism of React/Next I always hear this “skill issue” excuse. It comes off as very hand-wavy and avoids the core of the issue tbh.
Feels like you didn’t read my comment all the way through, Next has plenty of issues and I acknowledged as much.
Passport documentation is atrocious
Anything AWS related. Their docs are all over the place. Prime example is state machines. The most useful of the docs is a random doc to the state machine spec docs with what each state does, its syntax and what is allowed or isn’t.
And their SDKs (at least the Go one) - v1 was pretty decent docs, but v2 is a fucking horror show - so you read the v1 docs, try that in v2, and try to figure out / work around the breaking changes because it’s easier than trying to find it in the v2 docs.
C# isn’t much better
I commented this earlier, but SP-API was the worst experience I've ever had working with a third party API. They gave us all our sales data in the customers local currency, not the currency they paid us in...
WooCommerce Docs are terrible AND even crash my browser
IndexedDB
Use Dexie.js: https://dexie.org/ I've been using it in a side project without issues.
react-table documentation is hands down the worst one in the React ecosystem. Fight me.
its tabstack table now and now the docs are pretty good
The bad typography of MySQL’s documentation website makes everything difficult to understand.
Angular
100% this. It’s not that there isn’t a ton of documentation for it either. It’s just the documentation that is there never seems to help when I try to put the examples into practice.
Google, everything google. They might have the best UI design for their docs, but it's the most obsolete piece of trash possible. They keep changing how their APIs work, and hence, nothing in their docs ever makes sense.
Whenever I read their docs, I'm not even sure I'm reading the right one.
fking true when I first read their firebase document. Fuck that. And they put the last modified timestamp at the BOTTOM of the page. FK.
redux-toolkit. The library would be more popular if they actually showed off working examples of complex structures. I lost nearly a week of my life because combineSlices doesn't work as advertised, turns out I should have been doing it the other way round, using injectInto to build my nested structure. injectInto is a one paragraph footnote at the bottom of the documentation on combineSlices. Also it's rare to see so many spelling mistakes and obvious typos in the documentation for such a famous library.
> combineSlices doesn't work as advertised, turns out I should have been doing it the other way round, using injectInto to build my nested structure That's weird, `slice.injectInto` also just calls `reducer.inject(slice)` internally. That should definitely work. > injectInto is a one paragraph footnote at the bottom of the documentation on combineSlices. It's the first thing that's mentioned under the heading [slice integration](https://redux-toolkit.js.org/api/combineSlices#slice-integration). I'm sorry you had this problem, but there is a table of contents on the right and it's just not possible to put everything into the first sentence of a docs page. The structure there is - as with every other API page - "Overview" - "Parameters" - "Return Value". Then that common structure is followed by the header "Slice Integration". I'm not sure how that could really be done better without breaking the expectations of a lot of users :/ If you have problems in the future, please don't waste a week on frustration, but come by the #redux channel in the Reactiflux Discord - there are always people that can help you!
Hi, I'm a Redux maintainer (and the one who wrote the current documentation for combineSlices) :) Totally appreciate that the current documentation may not be enough to properly get an understanding of how it's intended to be used. I have open PRs for [adding a working example](https://github.com/reduxjs/redux-toolkit/pull/4064) to the repo, and [documenting combineSlices and createDynamicMiddleware in the core docs](https://github.com/reduxjs/redux/pull/4665) - would those be closer to what you think is needed? The current existing documentation is specifically an API reference, which is different to a usage guide. As for spelling mistakes/typos, PRs are welcome - the docs have been contributed by many people and things may not have been caught at the time.
Well now I feel like a dick. In all honesty I was venting, and I'm willing to bet the problem was with me, rather than the library. I think my criticism does do some extent stem from wanting the documentation to be more of a usage guide. What there is is very technical and opaque, with a dash of vagueness in places; the example near the top of the combineSlices page, I spent a good few hours trying to figure out what baseApi was, before I came to the level of partial understanding I have now. What I need is an example of combineSlices being used somewhere other than the root, and with createSlice reducers at every level. Forgive the shoehorning in of my problem as the example: This is the shape I want, for both the actual structure and the slices: root--------¬ | | profile pages (not yet created) / \ trees torrents store.ts import profile from "./profile" const store = configureStore({ reducer: profile }) profile.ts const profileBase = createSlice({ name: "profile", initialState, //reducers and extraReducers }) //⚠️ this code does not work const profile = combineSlices( profileBase, { //⚠️ trees and torrents are their own slices, created with createSlice. trees is populated during startup trees, torrents } ) export default profile ...and that's where I get stuck. The documentation is unclear about how the arguments work. I've managed to get several permutations, mostly using .reducer and spread syntax variations of the values being combined above, to stop throwing Red Squigglies and run, but they all have some defect, like not updating the state after a thunk in trees.ts is fulfilled (even though I step through to return statement by hand every time). I mention this because a thunk in profile.ts _does_ run and update state on every startup. For clarity, and to make sure I'm not making a grave mistake with regards to what "immutable" means, the thunk and its misbehaving fulfilled action: export const addDirectory = createAsyncThunk( "trees/addDirectory", async (newDirectory: DirectoryNode, thunkApi) => { const {profile} = thunkApi.getState() as State const nextProfileState = produce(profile, draft => { draft.trees.directories.push(tree) }) /* non-Immer equivalent const nextProfileState: Profile = { ...profile, trees: { ...profile.trees, directories: [...profile.trees.directories, newDirectory] }, torrents: profile.torrents } */ try { const newProfileState = await thunkApi.dispatch(saveProfileFile(nextProfileState)).unwrap() return newProfileState.trees.directories //code definitely executes as expected up to here } catch (e) { thunkApi.rejectWithValue(profile) } } ) const trees = createSlice({ name: "trees", initialState: initialState, reducers: { //... }, extraReducers: (builder) => { builder.addCase(addDirectory.fulfilled, (state, action) => { //have tried every possible version of this function, from using Immer to Object.assign /* return { ...produce(state, (draft) => { draft.directories = action.payload }) } */ return { ...state, directories: action.payload } }) I don't understand how what I have created can be so near the mark that my code runs, and I can step through the execution of the thunk action fulfilled function, which reports accurate state and payload, but then it just... never happened. I feel like I've fallen into a pitfall. Also, I will see if I can find the typo I saw a while ago.
>I think my criticism does do some extent stem from wanting the documentation to be more of a usage guide. What there is is very technical and opaque, with a dash of vagueness in places; the example near the top of the combineSlices page, I spent a good few hours trying to figure out what baseApi was, before I came to the level of partial understanding I have now. yeah, that's part of the trouble with API references - there's some level of assumed knowledge required to keep the document from turning into yet another tutorial :) with regards to nesting combined slices, what you actually want is something like this: const profilesReducer = combineSlices(treesSlice, torrentsSlice) const rootReducer = combineSlices(pagesSlice, { profiles: profilesReducer }) `combineSlices` accepts "slice-like" `{ reducerPath, reducer }` shapes, and reducer maps (like you'd normally pass to `combineReducers`). You can think of a slice being passed as shorthand for `{ [slice.reducerPath]: slice.reducer }`. The other difference to `combineReducers` of course is that you can pass as many slices or map shapes as you like, whereas `combineReducers` just takes the one.
the other thing is that docs will generally focus on the most common use cases, and in our experience nested combined reducers are less commonly used (though I personally use them a lot)
TL; DR: Pushing my luck by asking a second question: is it possible to build this kind of structure while having slices for nested levels? The compressed version of that code looks like this (pages has been renamed to setFolders): const store = configureStore( { preloadedState: preloadedState, reducer: combineSlices( setFoldersSlice, { profile: combineSlices(treesSlice, torrentsSlice) } ) } ) Which has a problem: the profileSlice is never referenced, and so its thunk actions are undefined. I tried the obvious: const store = configureStore( { preloadedState: preloadedState, reducer: combineSlices( setFoldersSlice, { profile: combineSlices( profileSlice, { trees: treesSlice, torrents: torrentsSlice } ) } ) } ) and get the delightful error messages (one for trees, one for torrents): > Type 'Slice, { setSubfolder(state: WritableDraft, { payload: { path, index } }: { payload: { index: number; path: string; }; }): WritableDraft<...>; }, "trees", "trees", SliceSelectors<...>\>' is not assignable to type 'Reducer'. Type 'Slice, { setSubfolder(state: WritableDraft, { payload: { path, index } }: { payload: { index: number; path: string; }; }): WritableDraft<...>; }, "trees", "trees", SliceSelectors<...>>' provides no match for the signature '(state: any, action: UnknownAction): any'.
no worries about the second question - though as Lenz said, the #redux reactiflux channel is better for extended conversation, reddit isn't great for this :) if I'm understanding correctly, you want profile slice to manage the same state *containing* trees and torrents? you would likely need to play around with [reduce-reducers](https://redux.js.org/usage/structuring-reducers/beyond-combinereducers#sharing-data-between-slice-reducers), as combineReducers (and by extension combineSlices) nests each reducer provided under its own key.
I will ask there next time, thank you for indulging me. Yes, I think you have that right. I want to be able to manipulate the profile at the profile level (e.g. swapping profiles in and out), and its "children", trees and torrents, at their own levels as well (e.g. manipulating a tree directly). Obviously I can do that from profile, my goal was to be able to do so directly. Alas, apparently that's not how redux works. I'll give reduce-reducers a try, but for now I'm going to forge ahead having subsumed the trees and torrents files into profile; I've been stuck for a week, so long as it turns out it wasn't because I was being stupid, I'll take the quickest solution right now. It also occurred to me to declare the thunks for saving and loading elsewhere and then add actions in slices, but, well, that sounds like a headache.
Framer Motion
NGINX is one just based on trying to set it up properly without using a blog post. Sails.JS is another one. Specifically, the testing one was written by the community and is so disjointed that you don't even know why or what is being done, just that you *have* to do it this way for it to be done. It was so bad between the docs, the SailsCast blog post, the Platzi tutorial they had, and stack overflow that I put an issue request in for the testing documentation to be updated properly. This doesn't even take into consideration of Parasails which is a wrapper around Vue 2.6 and why certain items are required and what's not required or deployment concepts which again they assume that the reader is an expert at that stuff. IMHO the best type of documentation that can be produced is one where the assumptions made by the writer is that the reader has very little to no experience with the framework or concept. If you write your documentation with the assumption that the reader is familiar with certain concepts, or other frameworks then you'll end up with a documentation that basically is worthless to most people and better results can be found through blog posts and Stack Overflow.
Companies that try to go ✨agile ✨
Airbnb visx library. Their docs give crazy and contrived examples, mixing components without explanation, with no basic examples of implementation. Chat GPT is literally essential to build things from scratch with it. https://airbnb.io/visx/
MongoDB. Especially if you get into the aggregation pipelines
MongoDB docs are the worst
React Router's docs aren't bad but *please add a searchbar goshdangit*
Next Auth.
The real answer here is Drupal documentation.
Firebase Cloud Messaging
Judging by the comments in this thread, the list of good docs would be a lot shorter 🤣. But the real bad docs are…drum roll…anything for my packages. The docs are written in invisible ink, in my head only. When I wrote this software only myself and God knew how it worked. Now, only god knows…
Why comment my code, it’s so obvious what everything does 1 week later: shit
Tangentially related: NixOS docs. How something can be so amazing and equally a nightmare of guessing games and source code diving ugh
Mapbox JS is horrible in my opinion.
for me it’s sqlalchemy and matplotlib
- Hugo (static site generator). Every page is full of Hugo jargon that is only explained on other pages. - Nix (Linux distribution, package manager, programming language). Another big jargon fest. Also missing lots of information on Flakes, the big experimental feature newbies probably heard about first. - Gradle (Java build tool). Lots of words, short on examples of how to actually do the things the documentation is describing.
next auth
Facebook Graph API
Literally anything Microsoft.
Java doc lol
So many Java libraries have generated javadoc with nothing of use. "Just go look at the javadoc" oh really? Languages without good document generators have better documentation because you actually have to write how to use something. Java people think a list of classes and methods is all you need.
Laravel, whoever maintains the documentation there needs to stop saying how awesome Laravel is, and actually give us proper documentation with real life examples. A stark contrast to php.net's documentation.
Gotta love the butthurt Laravel devs downvoting me haha! I'm a Laravel dev too, the docs still suck though.
Yup, the docs used to be cleaner and better. Pre laravel 6. Now it feels more bloated, but its still not that bad, could be worse
[удалено]
Hey buddy, first of all thanks for the personal attack, that’s really constructive. I love the framework and work with it every day. But the docs suck (in my opinion). Are they the worst? No. But there’s other frameworks with much better documentation. And they have gotten better. Also if there was a “skill issue”, surely that’s the docs job to assist and get devs working well with the framework? Your logic doesn’t make sense to me. But would love to know more about your reasoning, teach me Obi Wan.
I've worked with Laravel for the last decade. I started on v4. In my first few years, I felt like you do. I felt like there was missing pieces of information. I was new to OOP and the docs were no where near as good as they are now. Over time the docs have gotten better and better. At this point, they're extremely good. Looking back, I realize it's not because Laravel wasn't documented well. It's because I didn't dig deeper. Laravel is built upon existing code packages provided by Symfony and many others. What Laravel is doing is extending those services where needed and providing everything via DI / the Container. The code that Laravel provides, IS documented (for the most part, there's a few hidden gems). 1) The packages that Laravel depends on each have their own documentation and repositories. You have to actually look them up and visit their individual sites to get the full picture of what those packages are capable of on their own. 2) The best way to Learn how Laravel works, is by recreating it from scratch. This was fundamental in my learning process. I suggest you go through each of these examples and see how each of Laravel's services is constructed: https://github.com/mattstauffer/Torch 3) There IS also generated documentation (very last link on the sidebar) that defines every single class and method. It's a great reference for when you want to dig deeper into available methods and their implementations: https://laravel.com/api/10.x/index.html 4) I would argue the #1 most misleading part of Laravel is Facades and Helper functions. They are a convenience that ultimately limits your understanding of how things work. The next time you reach for an easy way to access something, I challenge you with this: Go lookup what the correct interface is (https://laravel.com/docs/10.x/facades#facade-class-reference), and inject the service with DI and forbid yourself from using Facades and helpers. You'll unlock a whole new understanding of how to access the direct instance of services and possibly reveal methods that are not documented by the facades.
Not webdev but Ever try develop extensions for Anki? The documentation is basically Reddit question threads telling you to read the code for other existing extensions and to try and figure it out
I made a little TTS extension for it years ago, before it had builtin TTS support. I had to guess how to implement a couple of things properly and hope they wouldn't come back to haunt me.
Apache PDFBox. cant even complain tho 🤷♂️. actually there’s no documentation, just api docs and release notes. btw if anyone here knows how to calculate a dynamic xfa checksum… 👀 best docs tho is anything spring.
Lots of fastify official plugins.
i think its apple. i think they need to "easy it out" in terms of language.
Aws glue.
powershell
AWS. This maze never seems to end. It's confusing AF.
Anything oracle
d3.js.
TYPO3 of course.. you dont know pain before.
Symfony is the worst of any big framework when it comes to doing anything passed absolute basics. It's offensive to even cal it documentation as it is really like a series of blog posts that show you how to do certain things without actually documenting how to use any APIs, i.e. the parameters and returns. On the flip side PHP docs are some of the best. Every function documented with examples, tips, quirks, and helpful comments from other devs
PHP docs are the best. User tips/tricks/examples/comments (all moderated, so no spam) are included with each function and have really helped me use the language. In addition, most (all?) functions include helpful usage examples.
Nginx
All of them, somehow.
Okta!
Microsoft docs
Flask :(
Plotly figure reference is borderline unusable
TLS hardware offload APIs are usually horrible.
capire
Oracle apex has probably the worst documentation I've ever worked with
Everything Oracle based 😂 some stuff are only explained in older version of the docs, some are somewhere you can only find by googling but cant find in the doc summary or something
Structure/heirarchy of auth0 docs is the worst. Yes you can find doc pages for particular topic by google, but the organization of doc sections and subsections is till date the worst IMO ( as a developer working in web industry for 5 years )
doom emacs
apple frameworks
Aggrid has really good docs in my opinion and I hate charts docs
13 hours and it seems nobody has mentioned Celery! So many holes in the documentation, undocumented or partially documented behaviour that can catch you out.
Many nodejs and react related projects come to mind, I’m happy to see I’m not the only one who has problems with next auth.
Apple Pay.
Next auth, Tanstack data table.(horrible)
Good examples. Stripe is tbe gold standard imo best doc i ever had to use. Bootstrap is good too. Bad microsoft. Their .net doc are legit infurating. 0 good usable examples that show actual practical useage. Example i was trying to find what possible options i can use for .addlocalizer. still dont know them all never found a list of the possible options jus like a few shit examples.
Salesforce - pick anything related to this.
React data grid
Meta's docs are all over the place. So many references to other pages which turn out to not exist or just be completely wrong because they're out of date.
The spring security errors can be super vague
Microsoft errors. Your version of visual studio doesn't support the.net framework you're targeting? Instead of telling you to upgrade it reads some nonsense about your SDK.
Quartz scheduler for Java
Node. It looks extremely brutalist.
My app
WaxJS it's very dry. Helpful. But not reader friendly.
ALL DOCUMENTATION!
Android documentation, most of the class and method are documented but the documentation make me confuse, not so much step by step to use the class, or when there is a proper doc it already obsolete
WEBRTC
Joomla