Core Presidium Documentation Refresh

Redesign/layout of splash page, refresh of Overview, and Key Concept sections. New sections added and a few other sections deleted (Features and Benefits sections in Overview,  inside Presidium, Presidium Workflow, and Time-saving Features in Key Concepts)

content/_key-concepts/02-supporting-learning-objectives.md

@@ -6,7 +6,7 @@ Presidium is more than a framework for producing documentation. It asks you to t
 
 # Supporting Learning Objectives & Efficiency
 
-Presidium recommends creating small 'micro' articles that convey enough information to fulfill a learning objective. Small articles are advantageous because they:
+Presidium recommends creating small micro-articles that convey enough information to fulfill a learning objective. Small articles are advantageous because they:
 * Usually only require a single author
 * Force the author to focus on effectively describe a single concept
 * Enable authors to quickly add documentation while also working on a product or service.

content/_key-concepts/04-templates.md

@@ -0,0 +1,7 @@
+---
+title: Templates
+---
+
+Presidium includes article templates for each of the pre-defined sections. Templates are text documents that contain instructions and Markdown which can be modified to meet your needs.
+
+Templates encourage consistency and provide a simple checklist that an author can use for inspiration. [Templates]({{site.baseurl}}/best-practices/#use-article-template)

content/_key-concepts/06-learning-objective.md

@@ -0,0 +1,13 @@
+---
+title: Learning Objectives
+---
+
+You should define the knowledge and skill set of your target audience before starting your documentation. You can then use this information to avoid wasting time explaining information your audience already knows.
+
+Just as stories are used to define software, learning objectives can be written using a standard template: *As a [user] of the [solution] I [know a specific piece of information] or can [perform a specific task]*
+
+
+For each learning objective, you should:
+
+* Identify what your audience should know and be able to do after they have read the documentation.
+* Use that information to create a list of learning objectives.

content/_key-concepts/05-markdown.md → content/_key-concepts/07-markdown.md

@@ -1,5 +1,5 @@
 ---
-title: Efficient Authoring With Markdown
+title: Markdown
 ---
 
 Markdown is an ubiquitous, lighweight markup language known to almost any engineer. If you don't know Markdown, it's easy to learn. Presidium uses a version of Markdown known as [Github Flavoured Markdown](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) and leverages this 'common tongue' to enable multiple contributors to create documentation quickly without wasting time doing **point & click** styling or having to alter HTML and CSS.

content/_key-concepts/08-presidium-microarticles.md

@@ -0,0 +1,14 @@
+---
+title: Micro-articles
+---
+
+Presidium is built on sound theoretical strategies for developing learning content and managing knowledge assets. The core of this approach is the development of specific focused micro-articles that explain individual concepts.
+
+This splits the problem of content development into two parts:
+
+1.	Defining a site outline based on the concepts that must be documented and how they should be sequenced and presented.
+2.	Developing articles that each explain each concept, using a standard template to ensure consistency.
+
+Micro-articles break the documentation development and maintenance activities into manageable chunks that can be prioritized based on need. In many cases, it's possible to write and review an article in under 20 minutes. [Writing Effecive Articles]({{site.baseurl}}/best-practices/#writing-effective-articles)
+
+This Presidium documentation site not only explains the Presidium software but also includes best practice guidelines for writing your documentation.

content/_key-concepts/09-reference-document-ingestion.md

@@ -0,0 +1,14 @@
+---
+title: Importing Reference Documents
+---
+
+Presidium can ingest marked up source code and API specs, allowing you to reuse existing documentation investments. Imported documentation will be included in the menu and sitemap.
+
+Presidium supports the following documentation sources:
+- [javadoc comments](#javadoc)
+- [jsdoc comments](#jsdoc)
+- [swagger api](#swagger)
+
+For other sources that do not yet have an importer, documentation can be [embedded](#embed) into references.
+
+Read more [here]({{site.baseurl}}/reference/importers/).

content/_key-concepts/10-content-maintenance.md

@@ -0,0 +1,8 @@
+---
+title:  Content Maintenance
+---
+
+Presidium is designed to make it easy to write and maintain your documentation. Instead of a monolithic document, Presidium manages a directory structure of micro-articles. The directory structure maps to the sections of your site, while the articles are joined together to build the content of each section. You can create a directory to add new sections and sub-sections. Each section contains a sample article template you can use as a starting point when creating new content. This site explains other best practices for writing articles.
+
+If you know how to maintain a codebase in a Github repository, you already know how to maintain Presidium documentation. You can use your team's current Github workflow to manage the approval and publication process and use Github's features to handle merge conflicts and other issues, just as you do for your source code.
+You can easily modify the suggested site structure and behavior. Most teams only need to remove a few sections that are not relevant to their project. Presidium has several configurable features that can be enabled as needed.

content/_key-concepts/11-publication-workflow.md

@@ -0,0 +1,13 @@
+---
+title:  Hosting & Versioning
+---
+
+You can host documentation on:
+
+* [Github]({{site.baseurl}}/recipes/hosting/): Use a simple command line utility to publish straight to your repository's Github pages.
+
+* [Bitbucket]({{site.baseurl}}/recipes/hosting/): Set up a separate repository to host your generated site.
+
+* [Custom]({{site.baseurl}}/recipes/hosting/): Build Presidium documentation using a continuous integration environment. The generated website can be served by a web host of your choice depending on your particular requirements.
+
+Presidium supports semantic versioning of your documentation when publishing to Github or Bitbucket pages. [Versioning]({{site.baseurl}}/recipes/versioning/)

content/_overview/01-features.md

@@ -1,36 +1,29 @@
 ---
-title:  Features
+title:  The Big Picture
 ---
 
 
-Presidium is an open-source software documentation creation system for Agile teams and their users.
+Presidium is an open-source, static website generator built on Jekyll for creating and maintaining software documentation for Agile teams and their users. Being static simplifies publication - you don't need to provision a server and can host your documentation in a matter of seconds on Github Pages or Bitbucket. You can easily include documentation publication in your continuous integration pipeline.
 
-Presidium is easy to install and configure, supports flexible content authoring and publishing workflows, and includes predefined article templates to quickly get you up and running.  A team can use Presidium to:
-* Develop new content
-* Rapidly re-purpose existing content
-* Re-use existing marked-up code (jsdoc, javadoc) and API specifications (Swagger)
+Presidium gives Agile teams a way to evangelize, explain, and support solutions to their peers so they can be correctly used and successfully adopted. Wikis can be unstructured and lose their value, tribal knowledge and content stored on Slack channels or emails can go into a black hole. Engineers are experts at writing code, not documentation. *Software documentation that doesn't suck* is not just a tagline.
 
-Presidium provides the features you need without the bloat of many commercial solutions:
+Presidium is based on sound theoretical strategies for developing learning content and managing knowledge assets. The core of this approach is the development of specific focused micro-articles that explain individual concepts. Predefined article templates and a menu structure get you up and running quickly.
 
-- **Automatic menus**
-  - The left navigation menu is dynamically created every time you publish your site. Various options are available to control navigation behavior.
+Presidium supports:
 
-- **Versioning**
-  - Support for multiple documentation versions. You can easily switch between versions without losing context.
+* **Automatic menus**: The left navigation menu is dynamically created every time you publish your site. Various options are available to control navigation behavior. [Menu Structure ]({{site.baseurl}}/key-concepts/#menu-structure-and-behavior)
 
-- **Markup Ingestion**
-  - Ingestion of markedup source code and API specs allow you to reuse existing documentation investments.
+* **Versioning**: Support for multiple documentation versions. You can easily switch between versions without losing context. [Versioning]({{site.baseurl}}/recipes/versioning/)
 
-- **Filtering by Role**
-  - Define user roles and filter site content by a specific selected role.
+* **Markup Ingestion**: Ingestion of markedup source code and API specs allow you to reuse existing documentation investments. [Importers]({{site.baseurl}}/reference/importers/)
 
-- **Link Checking**
-  - Make sure your links actually go somewhere!
+* **Filtering by Role**: Define user roles and filter site content by a specific selected role. [User Roles]({{site.baseurl}}/reference/front-matter/#user-roles)
 
-- **Article Status Tracking**
-  - Track the status of an article and manage simple authoring workflow.
+* **Link Checking**: Make sure your links actually go somewhere! [Link Validation]({{site.baseurl}}/tools/)
+
+* **Article Status Tracking**: Track the status of an article and manage simple authoring workflow. [Statuses]({{site.baseurl}}/reference/#directories)
+
+* **Themes**: Easily select and modify [Bootswatch](https://bootswatch.com/) themes that meet your brand requirements. [Themes]({{site.baseurl}}/reference/#themes)
 
-- **Themes**
-  - Easily select and modify [Bootswatch](https://bootswatch.com/) themes that meet your brand requirements.
 
 Presidium was created by [SPAN Digital](http://www.spandigital.com) and is licensed under [Apache 2.0](/updates/#license)