Comment by danpalmer | Hacker News Reader

Comment by danpalmer | Hacker News Reader

Parent Full thread

I don't use React much, but from a quick look at your docs now it looks like they are much better than last time I saw them, and I can't find any major points of criticism.

I like the fact that you have the separation between getting started/tutorials, main concepts, advanced concepts, and an API reference. The notes/caveats/etc seem reasonable.

It would be nice to link to the source in the API reference, and there are a lot of mentions of APIs that could be linked (pretty much any function name in a body of text could be linked I think), but apart from that these docs look great.

That said, I haven't had to use them day after day for 6 years like I have with the Django documentation!

One thing you might want to consider for the future would be switching between versions of React. Django has a version switcher at the bottom of the screen that lets you jump between versions, shows banners when reading the docs for unreleased/insecure/old versions (in case users are linked to them), and also mentions when APIs were added in recent versions in the text.

Thanks!

* Links to source: I use these frequently in other libraries, but I don't think this would be as useful for React, because we tend to have just a few functions each with a complicated implementation (vs programming stdlibs or other frameworks where many methods are on the order of 10-100 lines calling other public functions). Also our implementation isn't that easy to understand. I wonder if you had a particular use case in mind? * Linked method names: Good idea. * Version switcher: We've thought about this and will probably add it at some point.

Not wanting to open a can of worms, and I haven't read any of the React source, but if the source isn't that useful I'd suggest the answer might be to make the code easier to understand. Developers often need to dive into the code they are using for more detailed analysis of undocumented edge cases, tracking down bugs in their own code, etc, and having an understandable framework or library is fairly critical for that.

Django does a lot of complex/clever stuff under the hood, but the source is still readable, and in most cases fairly easy to understand.

This is just my 2 cents though.

Yes, making the source easy to understand is definitely valuable (even if only for our own team's understanding).

I believe Django's "functionality/(API surface)" quotient is still much lower than React's, which means it's easier to make the source useful to a newcomer.

Making complicated things easy to understand is much more simple in python than in js though.

Reply on news.ycombinator.com