diff --git a/index-tex.rst b/index-tex.rst
index 7758cfdade7c0a4b3630407169a82974f0816e02..68b6f76923425f1c25aa19d9c08ab6c05a30b9e1 100644
--- a/index-tex.rst
+++ b/index-tex.rst
@@ -10,8 +10,7 @@ BeagleBoard Docs
.. toctree::
- intro/blinkLED
- intro/index.rst
+ intro/index
boards/beagleplay/index
boards/beaglebone/ai-64/index
boards/beaglebone/ai/index
diff --git a/index.rst b/index.rst
index 3b66d81004eb8ede21b3a8bc79ffdda3400931a1..4a45688f7bb9efab7b7de86336c14c3f2de3840a 100644
--- a/index.rst
+++ b/index.rst
@@ -7,9 +7,7 @@ BeagleBoard Documentation
############################
Welcome to the `BeagleBoard project documentation <https://git.beagleboard.org/docs/docs.beagleboard.io>`__.
-
-Official documentation releases are provided at https://docs.beagle.cc (cached with local proxies) and
-https://docs.beagleboard.org (non-cached, without proxies).
+If you are looking for help with your Beagle open-hardware development platform, you've found the right place!
.. note::
The BeagleBoard.org Foundation is a US-based 501(c)3 non-profit organization providing open hardware
@@ -20,21 +18,26 @@ https://docs.beagleboard.org (non-cached, without proxies).
Introduction
************
-Get started engaging the BeagleBoard.org developer community by reading our :ref:`introduction` page.
+Get started quickly on our Linux-enabled boards with :ref:`blinkLED`, follow-up with articles in :ref:`intro_beagle-101`, and reach out
+via resources on our :ref:`support` page as needed to resolve issues
+and engage with the developer community. Don't forget that this is an open-source project! Your contributions are welcome.
+Learn about how to contribute to the BeagleBoard documentation project and any of the many open-source Beagle
+projects ongoing on our :ref:`contribution` page.
-* Read about how to get started and get help on our :ref:`support` page.
-* Learn how to contribute to the project on our :ref:`contribution` page.
+* Get started quickly at :ref:`blinkLED`.
+* Go a bit deaper at :ref:`intro_beagle-101`.
+* Read the book at :ref:`bone-cook-book-home`.
+* Get help from the community at :ref:`support`.
+* Learn how to contribute to the project at :ref:`contribution`..
.. toctree::
:maxdepth: 2
:hidden:
:caption: Introduction
- /intro/blinkLED
- /intro/support/index
/intro/beagle101/index
+ /intro/support/index
/intro/contribution/index
- CONTRIB
Boards
diff --git a/intro/blinkLED.rst b/intro/beagle101/blinkLED.rst
similarity index 100%
rename from intro/blinkLED.rst
rename to intro/beagle101/blinkLED.rst
diff --git a/intro/beagle101/index.rst b/intro/beagle101/index.rst
index f210f506f1d7e3738a7cb4caa26a1ee0e27603de..1af75f1b9caa8a00c72c27f29e3608f5815053d8 100644
--- a/intro/beagle101/index.rst
+++ b/intro/beagle101/index.rst
@@ -1,23 +1,43 @@
.. _intro_beagle-101:
-Beagle 101
-###########
+An Introduction to Beagles
+##########################
-.. note::
- This page is under construction. Most of the information here is drastically out of date.
+Linux-enabled boards
+********************
-This is a collection of articles to aide in quickly understanding how to make use of Beagles running Linux.
-Most of the useful information has moved to :ref:`bone-cook-book-home`, but some articles
-are being built here from a different perspective.
+Most Beagles have on-board flash preconfigured to run Linux. These resources will get you started quickly.
-Articles under construction or to be imported and updated:
+* Get started at :ref:`blinkLED`.
+* Learn to reset a board back to factory defaults and dive a bit deeper into the IDE at :ref:`beagleboard-getting-started`.
+* Learn a bit about Linux at :ref:`intro-linux`.
+* Learn about accessories at :ref:`accessories-home`
+* Learn about using 3rd party I2C add-on boards at :ref:`qwiic_stemma_grove_addons`.
+* Learn about using mikroBUS add-on boards at :ref:`beagleplay-mikrobus`.
+* Learn about using Cape add-on boards at :ref:`capes`.
+* Read :ref:`bone-cook-book-home`.
+* Read :ref:`pru-cookbook-home`.
+* Find more books at https://www.beagleboard.org/books.
-* :ref:`qwiic_stemma_grove_addons`
-* https://beagleboard.github.io/bone101/Support/bone101/
+Zephyr-enabled boards
+*********************
+
+Our Zephyr-enabled boards ship with a build of Micropython and, in the future, will also
+ship with a BeagleConnect Greybus node service for quick, transparent access from any BeagleConnect
+Greybus host enabled system.
+
+* See :ref:`beagleconnect-freedom-using-micropython` to get started quickly.
+* See :ref:`beagleconnect-freedom-using-zephyr` to learn to setup the Zephyr SDK.
+* See :ref:`beagleconnect-overview` to learn about BeagleConnect Greybus.
.. toctree::
:maxdepth: 1
:hidden:
- /intro/beagle101/qwiic-stemma-grove-addons.rst
+ blinkLED
+ linux
+ qwiic-stemma-grove-addons
+
+.. todo::
+ Make sure we have everything critical from https://beagleboard.github.io/bone101/Support/bone101/
diff --git a/intro/beagle101/linux.rst b/intro/beagle101/linux.rst
new file mode 100644
index 0000000000000000000000000000000000000000..5879384b62c229c7cab245a6091b46f00bf0081e
--- /dev/null
+++ b/intro/beagle101/linux.rst
@@ -0,0 +1,93 @@
+.. _intro_linux:
+
+An Introduction to Linux
+########################
+
+This article seeks to give you some quick exploration of Linux. For a deeper training,
+scroll down to :ref:`embedded-linux-training`.
+
+Linux is designed to make the details of the hardware it is running on not matter so much
+to users. It gives you a *somewhat* common experience on any hardware.
+
+It also goes a bit further, providing some description of the harware as part of the running
+"file system".
+
+Typical Command-line Utilities
+******************************
+
+Most of what a new user experiences with Linux is the command-line.
+
+.. table::
+
+ +=========+================================+=========+====================================+
+ | command | function | command | function |
+ +=========+================================+=========+====================================+
+ | pwd | *show current directory* | echo | *print/dump value* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | cd | *change current directory* | env | *dump environment variables* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | ls | *list directory contents* | export | *set environment variable* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | chmod | *change file permissions* | history | *dump command history* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | cp | *copy files* | man | *get help on command* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | mv | *move files* | apropos | *show list of man pages* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | rm | *remove files* | find | *search for files* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | mkdir | *make directory* | tar | *create/extract file archives* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | rmdir | *remove directory* | gzip | *compress a file* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | cat | *dump file contents* | gunzip | *decompress a file* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | less | *progressively dump file* | du | *show disk usage* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | vi | *edit file (complex)* | df | *show disk free space* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | nano | *edit file (simple)* | mount | *mount disks* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | head | *trim dump to top* | tee | *write dump to file in parallel* |
+ +---------+--------------------------------+---------+------------------------------------+
+ | tail | *trim dump to bottom* | hexdump | *readable binary dumps* |
+ +---------+--------------------------------+---------+------------------------------------+
+
+Kernel.org Documentation
+************************
+
+See https://www.kernel.org/doc.
+
+Linux Standard Base
+*******************
+
+See https://refspecs.linuxfoundation.org/lsb.shtml.
+
+.. shell-session::
+
+ $ lsb_release -a
+
+Filesystem Hierarchy Standard
+*****************************
+
+See https://www.pathname.com/fhs/
+
+Kernel Application Binary Interface
+***********************************
+
+See https://www.kernel.org/doc/Documentation/ABI/.
+
+Busybox
+*******
+
+Even though large distros like Debian and Ubuntu do not make extensive use of `busybox`, it is still very useful to
+learn
+
+See http://www.busybox.net/.
+
+.. _embedded-linux-training:
+
+Training
+********
+
+To continue learning more about Linux, we highly recommend https://bootlin.com/training/embedded-linux/.
diff --git a/intro/contribution/index.rst b/intro/contribution/index.rst
index 6f915c8c309cf6cb7d5857329c52ec79356b71f4..ea15b8f9e26fe856ecd0022aab6c418b81cd7280 100644
--- a/intro/contribution/index.rst
+++ b/intro/contribution/index.rst
@@ -53,12 +53,6 @@ the skills required for Linux contributions in the :ref:`beagleboard-linux-upstr
The most useful thing to know is how to ask smart questions. Read about this in the :ref:`intro-getting-support` section. If you ask
smart questions on the issue trackers and forum, you'll be doing a lot to help us improve the designs and documentation.
-.. toctree::
- :maxdepth: 1
- :hidden:
-
- /intro/contribution/linux-upstream
-
How can I contribute?
*********************
@@ -66,6 +60,8 @@ The most obvious way to contribute is using the `git.beagleboard.org Gitlab serv
bugs, suggest enhancements and providing merge requests, also called pull requests, the provide fixes to software, hardware
designs and documentation.
+Reading the `help guide <https://git.beagleboard.org/help/>`_ is a great way to get started using our Gitlab server.
+
This documentation has a number of ``todo`` items where help is needed that can be searched in the source.
.. todolist::
@@ -73,32 +69,47 @@ This documentation has a number of ``todo`` items where help is needed that can
Reporting bugs
===============
-.. todo::
- Describe where and how to report issues on git.beagleboard.org
+Start by reading the `Gitlab Issues help page <https://git.beagleboard.org/help/user/project/issues/index.md>`_.
+
+Please request an account and report any issues on the appropriate project issue tracker at https://git.beagleboard.org.
+
+Report issues on the software images at https://git.beagleboard.org/explore/topics/distros.
+
+Report issues on the hardware at https://git.beagleboard.org/explore/projects/topics/boards.
Suggesting enhancements
=======================
-.. todo::
- Describe how to introduct ideas on forum.beagleboard.org and git.beagleboard.org
+An issue doesn't have to be something wrong, it can just be about making something better. If in doubt how to make
+a productive suggestion, hop on the forum and live chat groups to see what other people say. Check the current
+ideas that are already out there and give us your idea. Try to be constructive in your suggestion. We are a primarily
+a volunteer community looking to make your experience better, as those that follow you, and your suggestion could be
+key in that endeavor.
+
+Where available, use the "enhancement" `label <https://git.beagleboard.org/help/user/project/labels.md>`_ on your issue
+to make sure we know you are looking for a future improvement, not reporting something critically wrong.
Submitting merge requests
=========================
-.. todo::
- Describe how to introduct ideas on forum.beagleboard.org and git.beagleboard.org
+If you want to contribute to a project, the most practical way is with a
+`merge request <https://git.beagleboard.org/help/user/project/merge_requests/index.html>`_. Start
+by `creating a fork <https://git.beagleboard.org/help/user/project/repository/forking_workflow.html>`_, which
+is your own copy of the project you can feel free to edit how you see fit. When ready,
+`create a merge request <https://git.beagleboard.org/help/user/project/merge_requests/creating_merge_requests.html>`_ and
+we'll review your work and give comments back to you. If suitable, we'll update the code to include your contribution!
-Style and usage guidelines
-**************************
+A bit more detailed suggestions can be found in the articles linked below.
-* :ref:`beagleboard-git-usage`
-* Git commit messages
-* :ref:`beagleboard-doc-style`
+Articles on contribution
+**************************
.. toctree::
:maxdepth: 1
- :hidden:
- /intro/contribution/git-usage
- /intro/contribution/style
- /intro/contribution/rst-cheat-sheet
+ /CONTRIBUTING
+ git-usage
+ style
+ rst-cheat-sheet
+ linux-upstream
+ /CONTRIB
diff --git a/intro/index.rst b/intro/index.rst
index e5e65cdda68db57302898e36ead8c201fa9aaa43..3777ea42d79e58ece8afe3ae7ea464cb0d06375e 100644
--- a/intro/index.rst
+++ b/intro/index.rst
@@ -1,10 +1,14 @@
+..
+
+ This adds content to the print version that is in /index.rst, but skipped in /index-tex.rst
+
.. _introduction:
Introduction
#############
-Welcome to the BeagleBoard documentation project. If you are looking for help with your Beagle
-open-hardware development platform, you've found the right place!
+Welcome to the `BeagleBoard project documentation <https://git.beagleboard.org/docs/docs.beagleboard.io>`__.
+If you are looking for help with your Beagle open-hardware development platform, you've found the right place!
.. important::
@@ -18,7 +22,8 @@ open-hardware development platform, you've found the right place!
* https://docs.beagleboard.io (straight from `docs repo <https://git.beagleboard.org/docs/docs.beagleboard.io>`_)
-Please check out our :ref:`support` page to find out how to get started, resolve issues,
+Get started quickly on our Linux-enabled boards with :ref:`blinkLED`, follow-up with articles in :ref:`intro_beagle-101`, and reach out
+via resources on our :ref:`support` page as needed to resolve issues
and engage with the developer community. Don't forget that this is an open-source project! Your contributions are welcome.
Learn about how to contribute to the BeagleBoard documentation project and any of the many open-source Beagle
projects ongoing on our :ref:`contribution` page.
@@ -27,12 +32,12 @@ projects ongoing on our :ref:`contribution` page.
Make sure you thoroughly read and agree with our :ref:`boards-terms-and-conditions` which covers
warnings, restrictions, disclaimers, and warranty for all of our boards. Use of either the boards or
the design materials constitutes agreement to the T&C including any modifications done to
- the hardware or software solutions provided by beagleboard.org foundation.
+ the hardware or software solutions provided by the BeagleBoard.org Foundation.
.. toctree::
:maxdepth: 2
- /intro/support/index
/intro/beagle101/index
+ /intro/support/index
/intro/contribution/index
diff --git a/intro/support/index.rst b/intro/support/index.rst
index f9935a81d4e0aa4a213e73563d82bbee4b3ebdda..137e588f04299e6c6bd057f7e446b1e7d17d7eb7 100644
--- a/intro/support/index.rst
+++ b/intro/support/index.rst
@@ -3,30 +3,26 @@
Support
#########
-Getting started
-***************
-
-The starting experience for all Beagles has been made to be as
-consistent as is possible. For any of the Beagle Linux-based open
-hardware computers, visit :ref:`beagleboard-getting-started`.
+First, read the manual
+**********************
-.. toctree::
- :maxdepth: 2
+Before reaching out for support, make sure you've gone through the process of resetting your
+board back to factory conditions.
- /intro/support/getting-started
+For any of the Beagle Linux-based open hardware computers, visit :ref:`beagleboard-getting-started`.
.. _intro-getting-support:
Getting support
***************
-BeagleBoard.org products and `open
-hardware <https://www.oshwa.org/definition/>`_ designs are supported
+BeagleBoard.org products are `open
+hardware <https://www.oshwa.org/definition/>`_ designs supported
via the on-line community resources. We are very confident in our
community’s ability to provide useful answers in a timely manner. If you
don’t get a productive response within 24 hours, please escalate issues
to Jason Kridner (contact info available on the `About
-Page <https://beagleboard.org/about>`_). In case it is needed, Jason
+Page <https://www.beagleboard.org/about>`_). In case it is needed, Jason
will help escalate issues to suppliers, manufacturers or others. Be sure
to provide a link to your questions on the `community
forums <https://forum.beagleboard.org>`_ as answers will be provided
@@ -71,14 +67,17 @@ Community resources
===================
Please execute the board diagnostics, review the hardware documentation,
-and consult the mailing list and IRC channel for support.
+and consult the form and live chat for support.
BeagleBoard.org is a “community†project with free support only given to
-those who are willing to discussing their issues openly for the benefit
+those who are willing to discuss their issues openly for the benefit
of the entire community.
- `Frequently Asked Questions <https://forum.beagleboard.org/c/faq>`_
-- `Mailing List <https://forum.beagleboard.org>`_
-- `Live Chat <https://beagleboard.org/chat>`_
+- `Forum <https://forum.beagleboard.org>`_
+- `Live Chat <https://www.beagleboard.org/discord>`_
+
+If you need to escalate an issue already reported over 24 hours ago on the `forum <https://forum.beagleboard.org>`_, please
+schedule a meeting to discuss it with Jason via contact information near the bottom of the `about page <https://www.beagleboard.org/about>`_.
.. _consulting-resources:
@@ -103,21 +102,4 @@ form:
Understanding Your Beagle
*************************
-- :ref:`intro_beagle-101`
-- `Hardware <https://beagleboard.org/Support/Hardware+Support>`_
-- `Software <https://beagleboard.org/Support/Software+Support>`_
-- :ref:`books-home`
-
- - :ref:`pru-cookbook-home`
- - :ref:`bone-cook-book-home`
- - `Exploring BeagleBone <https://beagleboard.org/ebb>`_
- - `Bad to the Bone <https://beagleboard.org/bad-to-the-bone>`_
-
-Working with Cape Add-on Boards
-*******************************
-
-- :ref:`capes`
-- :ref:`beaglebone-cape-interface-spec`
-- :ref:`accessories-home`
-
-
+Spend some time getting to know your Beagle via :ref:`intro_beagle-101`