1 files changed, 53 insertions, 40 deletions

diff --git a/meta-poky/README.poky.md b/meta-poky/README.poky.md
index 2ba3b5c03e..289373f944 100644
--- a/meta-poky/README.poky.md
+++ b/meta-poky/README.poky.md
@@ -1,71 +1,84 @@
 Poky
 ====
 
-Poky is an integration of various components to form a complete prepackaged
-build system and development environment. It features support for building
-customised embedded device style images. There are reference demo images
-featuring a X11/Matchbox/GTK themed UI called Sato. The system supports
-cross-architecture application development using QEMU emulation and a
-standalone toolchain and SDK with IDE integration.
+Poky is an integration of various components to form a pre-packaged
+build system and development environment which is used as a development and
+validation tool by the [Yocto Project](http://www.yoctoproject.org/). It
+features support for building customised embedded style device images
+and custom containers. There are reference demo images ranging from X11/GTK+
+ to Weston, commandline and more. The system supports cross-architecture
+application development using QEMU emulation and a standalone toolchain and
+SDK suitable for IDE integration.
 
 Additional information on the specifics of hardware that Poky supports
 is available in README.hardware. Further hardware support can easily be added
-in the form of layers which extend the systems capabilities in a modular way.
+in the form of BSP layers which extend the systems capabilities in a modular way.
+Many layers are available and can be found through the
+[layer index](https://layers.openembedded.org/).
 
 As an integration layer Poky consists of several upstream projects such as 
-BitBake, OpenEmbedded-Core, Yocto documentation and various sources of information 
-e.g. for the hardware support. Poky is in turn a component of the Yocto Project.
+[BitBake](https://git.openembedded.org/bitbake/),
+[OpenEmbedded-Core](https://git.openembedded.org/openembedded-core/),
+[Yocto documentation](http://git.yoctoproject.org/cgit.cgi/yocto-docs/),
+the '[meta-yocto](http://git.yoctoproject.org/cgit.cgi/meta-yocto/)' layer
+which has configuration and hardware support components. These components
+are all part of the Yocto Project and OpenEmbedded ecosystems.
 
 The Yocto Project has extensive documentation about the system including a 
-reference manual which can be found at:
-    http://yoctoproject.org/documentation
-
-OpenEmbedded-Core is a layer containing the core metadata for current versions
-of OpenEmbedded. It is distro-less (can build a functional image with
-DISTRO = "nodistro") and contains only emulated machine support.
-
-For information about OpenEmbedded, see the OpenEmbedded website:
-    http://www.openembedded.org/
+reference manual which can be found at <https://docs.yoctoproject.org/>
 
+OpenEmbedded is the build architecture used by Poky and the Yocto project.
+For information about OpenEmbedded, see the 
+[OpenEmbedded website](http://www.openembedded.org/).
 
 Contribution Guidelines
-=======================
+-----------------------
+
+The project works using a mailing list patch submission process. Patches
+should be sent to the mailing list for the repository the components
+originate from (see below). Throughout the Yocto Project, the README
+files in the component in question should detail where to send patches,
+who the maintainers are and where bugs should be reported.
 
 A guide to submitting patches to OpenEmbedded is available at:
 
-http://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded
+<http://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded>
 
 There is good documentation on how to write/format patches at:
 
-https://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines
-
+<https://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines>
 
 Where to Send Patches
-=====================
+---------------------
 
 As Poky is an integration repository (built using a tool called combo-layer),
 patches against the various components should be sent to their respective
 upstreams:
 
-bitbake:
-    Git repository: http://git.openembedded.org/bitbake/
-    Mailing list: bitbake-devel@lists.openembedded.org
+OpenEmbedded-Core (files in meta/, meta-selftest/, meta-skeleton/, scripts/):
+
+- Git repository: <https://git.openembedded.org/openembedded-core/>
+- Mailing list: openembedded-core@lists.openembedded.org
+
+BitBake (files in bitbake/):
+
+- Git repository: <https://git.openembedded.org/bitbake/>
+- Mailing list: bitbake-devel@lists.openembedded.org
+
+Documentation (files in documentation/):
+
+- Git repository: <https://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/>
+- Mailing list: docs@lists.yoctoproject.org
 
-documentation:
-    Git repository: http://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/
-    Mailing list: docs@lists.yoctoproject.org
+meta-yocto (files in meta-poky/, meta-yocto-bsp/):
 
-meta-poky, meta-yocto-bsp:
-    Git repository: http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto(-bsp)
-    Mailing list: poky@lists.yoctoproject.org
+- Git repository: <http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto>
+- Mailing list: poky@lists.yoctoproject.org
 
-Everything else should be sent to the OpenEmbedded Core mailing list.  If in
-doubt, check the oe-core git repository for the content you intend to modify.
-Before sending, be sure the patches apply cleanly to the current oe-core git
-repository.
+If in doubt, check the openembedded-core git repository for the content you
+intend to modify as most files are from there unless clearly one of the above
+categories. Before sending, be sure the patches apply cleanly to the current
+git repository branch in question.
 
-    Git repository: http://git.openembedded.org/openembedded-core/
-    Mailing list: openembedded-core@lists.openembedded.org
+[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/765/badge)](https://bestpractices.coreinfrastructure.org/projects/765)
 
-Note: The scripts directory should be treated with extra care as it is a mix of
-oe-core and poky-specific files from meta-poky.