nre-learning · Mierdin · Oct 24, 2018 · Oct 23, 2018 · Oct 23, 2018 · Oct 23, 2018
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,7 +1,15 @@
 # CHANGELOG
 
 ## In development
-- TBD
+
+### Curriculum
+
+- Fixed typos in YAML lesson (change) - [#109](https://github.com/nre-learning/antidote/pull/109) (contributed by pklimai)
+
+### Other
+
+- Significant restructuring of docs, and large improvements to contribution pages [#108](https://github.com/nre-learning/antidote/pull/108)
 
 ## v0.1.0
+
 - Initial release, announced and made public at NXTWORK 2018 in Las Vegas
diff --git a/check-changelog.sh b/check-changelog.sh
@@ -1,3 +1,4 @@
+git fetch origin master
 if echo $(git diff --name-only master) | grep -w CHANGELOG.md > /dev/null; then
     echo "Thanks for making a CHANGELOG update!"
     exit 0

diff --git a/docs/antidote-web/antidote-web.rst b/docs/antidote-web/antidote-web.rst
diff --git a/docs/architecture/architecture.rst → docs/architecture.rst b/docs/architecture/architecture.rst → docs/architecture.rst
@@ -1,25 +1,14 @@
 .. architecture:
 
-Antidote Architecture
+Architecture
 ================================
 
-.. toctree::
-   :maxdepth: 1
-
-   infrastructure.rst
-   lessonnetworking.rst
-   lessonscheduling.rst
-
-
 Antidote has multiple layers that build up a cluster, and multiple tools that run or setup each layer.
 
-In general, the Antidote cluster can be thought of like a Kubernetes cluster running many services. This cluster is designed to run atop any cloud IaaS with very few services outside of the cluster (e.g. ingress load balancing). Because we're not using hosted Kubernetes (e.g. GKE), we need to setup the group of virtual machines on which to install Kubernetes before we can even begin. To automate this task and make it multicloud portable, we are using general infrastructure-as-code tooling.
-
-The NRE Labs runtime of Antidote runs on Google Cloud Platform, so we'll use this as a example to illustrate the cluster and stack at a glance.
-
 .. image:: /images/infralayers.png
 
-Now let's overview the tiers that make up Antidote:
+Now let's overview the tiers that make up Antidote. The NRE Labs runtime of Antidote runs on Google Cloud Platform,
+so we'll use this as a example to illustrate the cluster and stack at a glance.
 
 +----------------------+--------------+--------------------------------------------------------------------------+
 | Infrastructure Tier  | Tool Used    |                              Explanation                                 |
@@ -55,7 +44,11 @@ Now let's overview the tiers that make up Antidote:
 |                      |              | the lab exercise steps.                                                  |
 +----------------------+--------------+--------------------------------------------------------------------------+
 
-Antidote provisions and manages Kubernetes as opposed to using a hosted, managed solution like GKE because:
+The first three layers are Antidote's "infrastructure". This means we are using existing tools and software to
+get to a working Kubernetes cluster. The final two components make up the :ref:`Antidote Platform <platform>`, which
+is the bulk of the custom software developed for the Antidote project.
+
+Antidote's infrastructure scripts provision and manages Kubernetes as opposed to using a hosted, managed solution like GKE because:
 
 - It needs a custom CNI plugin (multus). GKE doesn't support CNI except for very tightly controlled deployments.
   This means that we can't have multiple interfaces per pod. We tried our best to think of alternatives but the

diff --git a/docs/architecture/infrastructure.rst b/docs/architecture/infrastructure.rst
diff --git a/docs/community.rst b/docs/community.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -20,8 +20,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'antidote'
-copyright = '2018, Matt Oswalt'
-author = 'Matt Oswalt'
+copyright = '2018, Juniper Networks'
+author = 'Juniper Networks'
 # exclude_patterns = ['*DESCRIPTION.rst']
 
 # The short X.Y version

diff --git a/docs/contributing/contributing.rst b/docs/contributing/contributing.rst
diff --git a/docs/contributing/curriculum.rst b/docs/contributing/curriculum.rst
@@ -0,0 +1,97 @@
+.. _contrib-curriculum:
+
+Contributing to the Curriculum
+==============================
+
+Thanks for contributing to the Antidote curriculum. Before starting, please read this document in its entirety,
+so your work has the maximum impact and your time is best spent.
+
+Look at existing or in-progress content
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Read this document in its entirety
+
+After you have used NRE Labs, know the spirit of it’s break down of workflows as lessons with many quick stages/labs
+to progress through, and after you’ve read the quick contributing guide above, then it’s time to dirty your hands.
+
+4. Make a contribution goal for yourself (or anyone else) to fulfill by opening up a new issue with the “curriculum”
+label. Make sure you don’t conflict with an existing issue that is open and in progress. If you do conflict, then
+simply consider working together.  Here are those existing issues: https://github.com/nre-learning/antidote/issues?q=is%3Aopen+is%3Aissue+label%3Acurriculum
+Also make sure you don’t conflict with an existing lesson here: https://github.com/nre-learning/antidote/tree/master/lessons (also look
+here to see example of how other lessons are implmented until docs are better)
+5. Set off working.
+
+
+
+
+
+Lessons Should Demonstrate Something Useful
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Lessons in NRE Labs should demonstrate something useful to a network engineer.
+For instance, the first lesson is a simple NAPALM based python tool that
+collects system information about a target device.
+
+If a user can easily replicate what is shown in the lab so that it can help
+them in production, then this would be even better.
+
+Planning Lessons
+^^^^^^^^^^^^^^^^^^^^^^
+
+**One-off**
+
+There are multiple ways to build lessons in NRElabs.  The simplest method is
+to have single one-off lessons that do not have any direct relationship to
+other lessons.
+
+**Repeat**
+
+Some lessons can be repeated 2 or 3 times.  For instance, in addition to the
+NAPALM lesson, you could show the user how to collect system information using
+an alternate method.  You should explain why a network engineer would want to
+choose one method over another.  In the case of the first lesson, NAPALM is a
+somewhat limited tool.  If the user needs additional information, they would
+need to do something different.  They could use PyEZ, for instance.
+
+**Workflow**
+
+Some lessons could be a group of inter-related tasks.  A troubleshooting
+workflow that helps a network engineer locate a device in the network, or the
+path between two devices, could be broken up into a set of distinct tasks.
+Not every task has to be automated, but some could be, and the lessons could
+reflect this.
+
+**Considerations**
+
+There are a number of languages, tools, and libraries/packages that could be
+leveraged to build a lesson.  Consider using open-source tools for the lessons,
+or tools that are at least free.  This helps ensure that a user could more
+easily replicate what is shown in the lesson.
+
+
+
+
+
+Lesson Details
+^^^^^^^^^^^^^^^^^^^^^^
+
+The best way to get started building lessons is to get an instance of Antidote
+running on your own laptop. Ironing out all of the bugs before you submit a pull
+request makes the review process much smoother. For more info, see the
+:ref:`local build <buildlocal>` documentation.
+
+You'll also want to get familiar with the :ref:`syringe file <syringefile>` documentation.
+
+**Required lab components**
+
+syringe file
+readme for the lab
+html layout
+Default configs
+
+tabs will be determined via syringefile and rendered from jinja2 template at
+build time.
+
+The :ref:`Syringe YAML file <syringefile>` is the main descriptor of a lesson. It is here
+that a lesson is defined, it's properties and stages declared, and resources like configs,
+scripts, and playbooks referenced.
diff --git a/docs/contributing/general.rst b/docs/contributing/general.rst
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
@@ -0,0 +1,25 @@
+.. _contrib:
+
+Contributing to Antidote
+================================
+
+.. toctree::
+   :maxdepth: 1
+
+   curriculum.rst
+   platform.rst
+   ptr.rst
+
+In general, there are two area in which to contribute to Antidote:
+
+- The Lesson Curriculum - this is the most popular place to contribute to
+  Antidote. Here, you can change or add new lessons that describe automation
+  workflows. Before getting started, please read the
+  :ref:`lesson contribution guide <contrib-curriculum>`.
+- The Antidote Platform - there are a number of software projects that power
+  Antidote, and these are also open source. Please visit the
+  :ref:`platform contribution guide <contrib-platform>` before looking to
+  contribute here.
+
+Before starting work on a contribution, please read the relevant contribution guide;
+they contain vital information to ensure your time is well-spent.