Redo the introduction

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

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

intro/beagle101/index.rst

 .. _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/

intro/beagle101/linux.rst

+.. _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/.

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

intro/index.rst

+..
+
+   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
 

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`