2 files changed, 117 insertions, 1 deletions

diff --git a/documentation/index.rst b/documentation/index.rst
index 4fd1dfba18..7b60a527e1 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -16,7 +16,7 @@ Welcome to The Yocto Project's documentation!
 
    Quick Build <brief-yoctoprojectqs/brief-yoctoprojectqs>
    what-i-wish-id-known
-   Transitioning to a custom environment for systems development <https://www.yoctoproject.org/docs/transitioning-to-a-custom-environment>
+   transitioning-to-a-custom-environment
    Yocto Project Software Overview <https://www.yoctoproject.org/software-overview/>
    Tips and Tricks Wiki <https://wiki.yoctoproject.org/wiki/TipsAndTricks>
 
diff --git a/documentation/transitioning-to-a-custom-environment.rst b/documentation/transitioning-to-a-custom-environment.rst
new file mode 100644
index 0000000000..6f75aa746e
--- /dev/null
+++ b/documentation/transitioning-to-a-custom-environment.rst
@@ -0,0 +1,116 @@
+.. SPDX-License-Identifier: CC-BY-2.0-UK
+
+=============================================================
+Transitioning to a custom environment for systems development
+=============================================================
+
+|
+
+.. note::
+
+   So you've finished the :doc:`brief-yoctoprojectqs/brief-yoctoprojectqs` and
+   glanced over the document :doc:`what-i-wish-id-known`, the latter contains
+   important information learned from other users. You’re well prepared. But
+   now, as you are starting your own project, isn’t exactly straightforward what
+   to do. And, the documentation is daunting. We’ve put together a few hints to
+   get you started.
+
+#. **Make a list of the processor, target board, technologies, and capabilities
+   that will be part of your project**.
+   You will be finding layers with recipes and other metadata that support these
+   things, and adding them to your configuration. (See #3)
+
+#. **Set up your board support**.
+   Even if you’re using custom hardware, it might be easier to start with an
+   existing target board that uses the same processor or at least the same
+   architecture as your custom hardware. Knowing the board already has a
+   functioning Board Support Package (BSP) within the project makes it easier
+   for you to get comfortable with project concepts.
+
+#. **Find and acquire the best BSP for your target**.
+   Use the :yocto_home:`Yocto Project curated layer index
+   </software-overview/layers/>` or even the `OpenEmbedded layer index
+   <https://layers.openembedded.org>`_ to find and acquire the best BSP for your
+   target board. The Yocto Project layer index BSPs are regularly validated. The
+   best place to get your first BSP is from your silicon manufacturer or board
+   vendor – they can point you to their most qualified efforts. In general, for
+   Intel silicon use meta-intel, for Texas Instruments use meta-ti, and so
+   forth. Choose a BSP that has been tested with the same Yocto Project release
+   that you’ve downloaded. Be aware that some BSPs may not be immediately
+   supported on the very latest release, but they will be eventually.
+
+   You might want to start with the build specification that Poky provides
+   (which is reference embedded distribution) and then add your newly chosen
+   layers to that. Here is the information :ref:`about adding layers
+   <dev-manual/dev-manual-common-tasks:Understanding and Creating Layers>`.
+
+#. **Based on the layers you've chosen, make needed changes in your
+   configuration**.
+   For instance, you’ve chosen a machine type and added in the corresponding BSP
+   layer. You'll then need to change the value of the MACHINE variable in your
+   configuration file (build/local.conf) to point to that same machine
+   type. There could be other layer-specific settings you need to change as
+   well. Each layer has a README document that you can look at for this type of
+   usage information.
+
+#. **Add a new layer for any custom recipes and metadata you create**.
+   Use the "bitbake-layers create-layer" tool for Yocto Project 2.4+
+   releases. If you are using a Yocto Project release earlier than 2.4, use the
+   "yocto-layer create" tool. The "bitbake-layers" tool also provides a number
+   of other useful layer-related commands. See
+   :ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the
+   \`\`bitbake-layers\`\` script` section.
+
+#. **Create your own layer for the BSP you're going to use**.
+   It is not common that you would need to create an entire BSP from scratch
+   unless you have a *really* special device. Even if you are using an existing
+   BSP, :ref:`create your own layer for the BSP <bsp-guide/bsp:creating a new
+   bsp layer using the \`\`bitbake-layers\`\` script>`. For example, given a
+   64-bit x86-based machine, copy the conf/intel-corei7-64 definition and give
+   it a machine a relevant name (think board name, not product name). Make sure
+   the layer configuration is dependent on the meta-intel layer (or at least,
+   meta-intel remains in your bblayers.conf). Now you can put your custom BSP
+   settings into your layer and you can re-use it for different applications.
+
+#. **Write your own recipe to build additional software support that isn't
+   already available in the form of a recipe**.
+   Creating your own recipe is especially important for custom application
+   software that you want to run on your device. Writing new recipes is a
+   process of refinement. Start by getting each step of the build process
+   working beginning with fetching all the way through packaging. Next, run the
+   software on your target and refine further as needed. See :ref:`Writing a New
+   Recipe <dev-manual/dev-manual-common-tasks:writing a new recipe>` in the
+   Yocto Project Development Tasks Manual for more information.
+
+#. **Now you’re ready to create an image recipe**.
+   There are a number of ways to do this. However, it is strongly recommended
+   that you have your own image recipe - don’t try appending to existing image
+   recipes. Recipes for images are trivial to create and you usually want to
+   fully customize their contents.
+
+#. **Build your image and refine it**.
+   Add what’s missing and fix anything that's broken using your knowledge of the
+   :ref:`workflow <sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk
+   workflow>` to identify where issues might be occurring.
+
+#. **Consider creating your own distribution**.
+   When you get to a certain level of customization, consider creating your own
+   distribution rather than using the default reference distribution.
+
+   Distribution settings define the packaging back-end (e.g. rpm or other) as
+   well as the package feed and possibly the update solution. You would create
+   your own distribution in a new layer inheriting from Poky but overriding what
+   needs to change for your distribution. If you find yourself adding a lot of
+   configuration to your local.conf file aside from paths and other typical
+   local settings, it's time to :ref:`consider creating your own distribution
+   <dev-manual/dev-manual-common-tasks:creating your own distribution>`.
+
+   You can add product specifications that can customize the distribution if
+   needed in other layers. You can also add other functionality specific to the
+   product. But to update the distribution, not individual products, you update
+   the distribution feature through that layer.
+
+#. **Congratulations! You're well on your way.**
+   Welcome to the Yocto Project community.
+
+.. include:: /boilerplate.rst