New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update docs to use hooks #1788
Comments
Since we are having the discussion at #1782, closing this one out. |
Slightly different issue @saranshkataria - this pertains to the docs, not the tutorial |
ah, my bad. But why would we want everything to be hooks in the docs? There's a section about hooks and that is what it should be? |
On mobile now, but in short: if the Preferred Way of React going forward is using hooks for stuff like state and side effects, I think we should rewrite the docs so that they mirror that message. Right now, that’s not the case. Have a look here: https://reactjs.org/docs/state-and-lifecycle.html Class components and lifecycles definitely need to be documented, but perhaps not as... «the first choice», if you know what i mean. |
I don't think the docs should be preferring one way over the other yet, everyone is still figuring hooks out, but will reopen this issue to let other people share their opinions on it. |
As of now, though, the docs are preferring class components, by not even mentioning hooks (at least in that section) |
RADME.md in facebook/react repo says:
Following the link takes a newcomer to a page where all components are classes. This is quite confusing. Given that the stateful logic can be expressed using hooks now, classes can be revealed much later. |
I feel the same about the Main Concepts docs. Especially the "State and Lifecycle" doc. I was expecting to see at least a mention about Hooks there. Newcomers to React (especially folks coming from other libraries) could choose to check the Docs instead of the Tutorial (depending on their style of learning) so the Hooks section being after Advanced Guides and even the API Reference makes them somehow easy to miss. Having a brief mention of Hooks as an alternative to classes could be really helpful. |
The hook docs recommend using hooks rather than classes for new components (see Should I use Hooks, classes, or a mix of both?). The docs should primarily focus on hooks to be consistent with this suggestion, and save time by not requiring users to learn classes before they can learn hooks. With docs rewritten in hooks, we'd have to decide how to handle the old class docs. Is the class API going to change in the future, making it useful to maintain the original class docs in full as a separate verison? If not, should we stop updating the class docs or move them to a subsection of the hook docs (kinda like how hook docs are a subsection of the class docs now)? |
I'm making progress on converting the docs to use hooks instead of classes, and I'll submit a pull request when it's mostly complete. Then we can figure out if it's okay to replace the class docs or if the hook docs should be reworked in a different way. |
I've started a draft pull request, I'm not done checking it for accuracy but I'd still appreciate feedback: #2400 |
Since hooks are such a big change, and many people will be needing to learn react using classes, is it an option to provide examples, one using hooks and one using classes? Perhaps tab separated or something? I think this would also aid with people who want to refactor class code to functional components, as well as ensuring new code projects and people new to react start off learning hooks. |
I don’t think that’s a good idea because the hook API is designed very differently. There’s some overlap with some usages of hooks and classes, but there are enough differences and quirks that I think it would be easiest to explain them separately. There are already some references that compare basic hook usage with basic class usage anyway. Also the React team is planning on rewriting the docs from scratch fo hooks anyway, so the structure is going to differ (as it should because they don't really translate to each other directly). |
In case this can be useful to anyone else: @nickmccurdy's incomplete but very useful version of the docs with React hooks is online at https://reacthooks.nickmccurdy.com |
This comment has been minimized.
This comment has been minimized.
Just wanted to note this is still very much on our minds. We might start looking into this soon-ish. One challenge is how to coordinate translations. Since this is a big rewrite. cc @tesseralis curious if you have tips on how we could approach this. |
@gaearon when replacing class components with the function ones in the docs, is the plan to use It'd be great if this thread included a link to the guidelines (or their ongoing discussion). That feels quite relevant. |
I don't think there would be any significant impact given we've used |
@gaearon I don't think there should be a significant problem, although it might cause a headache with some languages that aren't as active. I'll check in over the weekend and see if there are any issues and see what's the best way to communicate this change to people. |
I think "Tutorial" is the highest priority than others because beginners would check the Tutorial page first. I don't want to recommend beginners the current Tutorial page because the Tutorial is written based on class components. It needs many works for translation, but it shouldn't block the migration. |
If anyone finds it helpful in the meantime, there's a newer fork of the docs that's more up to date than mine: https://reactwithhooks.netlify.app/ |
React documentation is currently being rewritten from scratch and is a WIP. |
As of now, the main docs haven’t been updated to account for hooks. Especially the state & lifecycle section seems a bit misleading now.
I’d love to help out with a rewrite, but I’d love to hear your feedback on what should be changed and what should stay behind.
The text was updated successfully, but these errors were encountered: