Clarify useLinkBuilder docs

Author: satya164

versioned_docs/version-5.x/use-link-builder.md

@@ -6,20 +6,20 @@ sidebar_label: useLinkBuilder
 
 > Note: This API is experimental and might change in a minor version.
 
-The `useLinkBuilder` hook let's us build a path to use for links based on a `navigate` action. It returns a function that takes `name` and `params` for the screen to navigate to and returns path based on the [`linking` options](navigation-container.md#linking).
+The `useLinkBuilder` hook let's us build a path to use for links for a screen in the current navigator's state. It returns a function that takes `name` and `params` for the screen to focus and returns path based on the [`linking` options](navigation-container.md#linking).
 
 ```js
-import { Link, useLinkBuilder } from '@react-navigation/native';
+import { Link, CommonActions, useLinkBuilder } from '@react-navigation/native';
 
 // ...
 
-function DrawerContent({ state, navigation, descriptors }) {
+function DrawerContent({ state, descriptors }) {
   const buildLink = useLinkBuilder();
 
   return state.routes((route) => (
     <Link
       to={buildLink(route.name, route.params)}
-      action={navigation.navigate(route.name)}
+      action={CommonActions.navigate(route.name)}
     >
       {descriptors[route.key].options.title}
     </Link>
@@ -29,4 +29,7 @@ function DrawerContent({ state, navigation, descriptors }) {
 
 This hook is intended to be used in navigators to show links to various pages in it, such as drawer and tab navigators. If you're building a custom navigator, custom drawer content, custom tab bar etc. then you might want to use this hook.
 
-It's important to note that `useLinkBuilder` doesn't consider bubbling of the `navigate` action when building the link. So the screen to navigate to must be present in the navigator it's used in. For example, in the above case, the navigator containing `Home` should also contain the `Profile` screen.
+There are couple of important things to note:
+
+- The destination screen must be present in the current navigator. It cannot be in a parent navigator or a navigator nested in a child.
+- It's intended to be only used in custom navigators to keep them reusable in multiple apps. For your regular app code, use paths directly instead of building paths for screens.

versioned_docs/version-5.x/web-support.md

@@ -13,7 +13,9 @@ Currently, the following features are available:
 - [URL integration in browser](configuring-links.md)
 - [Accessible links](link.md)
 
-Some navigators are also configured differently on web or provide additional web specific features:
+It's important to use links as the primary way of navigation instead of navigation actions such as `navigation.navigate`. It'll ensure that your links are properly usable on web.
+
+Some of the navigators are also configured differently on web or provide additional web specific features:
 
 1. The [drawer](drawer-navigator.md) and [bottom tab](bottom-tab-navigator.md) navigators show hyperlinks in the drawer sidebar and tab bar respectively.
 2. Swipe gestures are not available on [drawer](drawer-navigator.md) and [stack](stack-navigator.md) navigators when using on the web.