content updates

_data/sidebar_doc.yml

@@ -320,21 +320,21 @@ entries:
           product: all
           version: all
 
-        - title: Shuffle
+        - title: Shuffle layout
           url: /doc_shuffle.html
           audience: writers, designers
           platform: all
           product: all
           version: all
 
-        - title: FAQ pages
+        - title: FAQ layout
           url: /doc_faq.html
           audience: writers, designers
           platform: all
           product: all
           version: all
 
-        - title: Glossaries
+        - title: Glossary layout
           url: /doc_glossary.html
           audience: writers, designers
           platform: all

_includes/custom/doc/links_doc.html

@@ -41,7 +41,7 @@
 {% capture doc_getting_started %}<a href="doc_getting_started.html">Getting started with this theme</a>{% endcapture %}
 {% capture doc_getting_started_i %}<a href="doc_getting_started.html">{% endcapture %}
 
-{% capture doc_glossary %}<a href="doc_glossary.html">Glossary</a>{% endcapture %}
+{% capture doc_glossary %}<a href="doc_glossary.html">Glossary layout</a>{% endcapture %}
 {% capture doc_glossary_i %}<a href="doc_glossary.html">{% endcapture %}
 
 {% capture doc_help_api %}<a href="doc_help_api.html">Help API and UI tooltips</a>{% endcapture %}

css/customstyles.css

@@ -157,9 +157,7 @@ table > colgroup + thead > tr:first-child > td,
 table > thead:first-child > tr:first-child > td {
   border-top: 0;
 }
-table > tbody + tbody {
-  b
-}
+
 table > tbody > tr:nth-of-type(odd) {
   background-color: #f9f9f9;
 }
@@ -779,6 +777,13 @@ pre {
     margin: 25px 0px;
 }
 
+.panel-heading {
+    font-weight: bold;
+}
+#json-box-container pre {
+    margin: 0px;
+}
+
 p.dataType {display: block; font-color: gray; font-size: 80%;}
 
 dd {margin-left:20px;}

doc_excluding_files.md

@@ -20,6 +20,7 @@ exclude:
 
 If you have different outputs for your site, you'll want to customize the exclude sections in your various configuration files.
 
+## Exclude strategies
 Here's the process I recommend. Put all files in the root directory of your project. Suppose one project's name is alpha and the other is beta. Then name each file as follows:
 
 * alpha_sample.html

doc_faq.html

@@ -1,5 +1,5 @@
 ---
-title: FAQ
+title: FAQ layout
 tags: [special-layouts]
 keywords: frequently asked questions, FAQ, question and answer, collapsible sections, expand, collapse
 last_updated: August 12, 2015

doc_glossary.md

@@ -1,5 +1,5 @@
 ---
-title: Glossaries
+title: Glossary layout
 tags: [formatting, special-layouts]
 keywords: definitions, glossaries, terms, style guide
 last_updated: August 12, 2015

doc_help_api.md

@@ -3,7 +3,7 @@ title: Help APIs and UI tooltips
 tags: [publishing, single-sourcing, content-types]
 last_updated: August 12, 2015
 keywords: API, content API, UI text, inline help, context-sensitive help, popovers, tooltips
-summary: "You can loop through files and generate a JSON file that developers can consume like a help API. Developers can pull in values from the JSON into interface elements, styling them as popovers for user interface text. The beauty of this method is that the UI text remains in the help system and isn't hard-coded into the UI."
+summary: "You can loop through files and generate a JSON file that developers can consume like a help API. Developers can pull in values from the JSON into interface elements, styling them as popovers for user interface text, for example. The beauty of this method is that the UI text remains in the help system and isn't hard-coded into the UI."
 ---
 {% include linkrefs.html %}
 

doc_multibuild_pdf.sh

@@ -6,5 +6,5 @@ prince --javascript --input-list=../doc_writers-pdf/prince-file-list.txt -o /Use
 echo "Building the Designers PDF ..."
 prince --javascript --input-list=../doc_designers-pdf/prince-file-list.txt -o /Users/tjohnson/projects/documentation-theme-jekyll/doc_designers_pdf.pdf;
 
-# All done.
-# Now run . doc_multiweb_pdf.sh
+echo "All done."
+echo "Now run . doc_multibuild_web.sh"

doc_shuffle.html

@@ -21,6 +21,7 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
       <button class="btn btn-primary" data-group="getting-started">Getting Started</button>
       <button class="btn btn-primary" data-group="formatting">Formatting</button>
       <button class="btn btn-primary" data-group="publishing">Publishing</button>
+      <button class="btn btn-primary" data-group="content-types">Content types</button>
           <button class="btn btn-primary" data-group="single-sourcing">Single Sourcing</button>
       <button class="btn btn-primary" data-group="special-layouts">Special Layouts</button>
     </div>      
@@ -30,7 +31,7 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
 
     <div class="col-xs-6 col-sm-4 col-md-4" data-groups='["getting-started"]'>
 
-               <div class="panel panel-danger">
+               <div class="panel panel-default">
                <div class="panel-heading">Getting started</div>
                <div class="panel-body">
                   If you're getting started with Jekyll, see the links in this section. It will take you from the beginning level to comfortable. 
@@ -49,7 +50,23 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
     </div>
    
 
-    <div class="col-xs-6 col-sm-4 col-md-4" data-groups='["news"]'>
+    <div class="col-xs-6 col-sm-4 col-md-4" data-groups='["content-types"]'>
+
+        <div class="panel panel-default">
+            <div class="panel-heading">Content types</div>
+            <div class="panel-body">
+                This section lists different content types and how to work with them.
+                <ul>
+                    {% for page in site.pages %}
+                    {% for tag in page.tags %}
+                    {% if tag == "content-types" %}
+                    <li><a href="{{page.url}}">{{page.title}}</a></li>
+                    {% endif %}
+                    {% endfor %}
+                    {% endfor %}
+                </ul>
+            </div>
+        </div>
         
     </div>
 
@@ -57,7 +74,7 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
 
     <div class="col-xs-6 col-sm-4 col-md-4" data-groups='["formatting"]'>
 
-                <div class="panel panel-danger">
+                <div class="panel panel-default">
                <div class="panel-heading">Formatting</div>
                <div class="panel-body">
                   These topics get into formatting syntax, such as images and tables, that you'll use on each of your pages: 
@@ -81,7 +98,7 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
          
       <div class="panel panel-default">
                <div class="panel-heading">Single Sourcing</div>
-               <div class="panel-body">These topics cover strategies for single-sourcing:
+               <div class="panel-body">These topics cover strategies for single-sourcing. Single sourcing refers to strategies for re-using the same source in different outputs for different audiences or purposes.
                <ul>
                 {% for page in site.pages %}
                 {% for tag in page.tags %}
@@ -98,9 +115,9 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
 
        <div class="col-xs-6 col-sm-4 col-md-4" data-groups='["publishing"]'>
 
-<div class="panel panel-primary">
+           <div class="panel panel-default">
                <div class="panel-heading">Publishing</div>
-               <div class="panel-body">
+               <div class="panel-body">When you're building, publishing, and deploying your Jekyll site, you might find these topics helpful.
                    <ul>
                 {% for page in site.pages %}
                 {% for tag in page.tags %}
@@ -117,7 +134,7 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
 
         <div class="col-xs-6 col-sm-4 col-md-4" data-groups='["special-layouts"]'>
 
-             <div class="panel panel-warning">
+             <div class="panel panel-default">
                <div class="panel-heading">Special Layouts</div>
                <div class="panel-body">
                   These pages highlight special layouts outside of the conventional page and TOC hierarchy.
@@ -144,6 +161,6 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
 {% include initialize_shuffle.html %}
 {% endunless %}
 
-{{note}} This was mostly an experiment to see if there was a better way to document a long JSON code example. I haven't actually used this approach in my own documentation.{{end}}
+{{note}} This was mostly an experiment to see if I could break away from the hierarchical TOC and provide a different way of arranging the content. However, this layout is somewhat problematic because it doesn't allow you to browse other navigation options on the side while viewing a topic.{{end}}
 
 

doc_tag_archives_overview.md

@@ -3,7 +3,11 @@ title: Tag archives overview
 keywords: archives, tagging
 last_updated: August 12, 2015
 tags: [navigation]
-summary:
+summary: "This is an overview to the tag archives section. Really the only reason this section is listed explicitly in the TOC here is to demonstrate how to add a third-level to the navigation."
 ---
 
-This is an overview to the tag archives section. Really the only reason this section is listed explicitly in the TOC here is to demonstrate how to add a third-level to the navigation.
+## Reasons for tags
+
+Tags provide alternate groupings for your content. In the documentation for this theme, there are a number of equally plausible ways I could have grouped the content. The folder names and items I chose for each item could have been grouped in other ways with good reason.
+
+Tags allow you to go beyond the traditional hierarchical classification and provide other groupings. For example, the same item can belong to two different groups. You can also introduce other dimensions not used in your table of contents, such as platform-specific tags or audience-specific tags.

doc_theme_customization.md

@@ -3,7 +3,7 @@ title: Theme customization
 tags: [getting-started]
 last_updated: August 12, 2015
 keywords: getting started, customization, beginning steps, modifying the theme, modification
-summary: 
+summary: "You start customizing the theme by gutting the existing content in this theme and replacing it with your own content. Start with the configuration files, then customize the data files, and add your own markdown pages in the root directory."
 ---
 {% include linkrefs.html %} 
 

doc_themes.md

@@ -3,15 +3,16 @@ title: Themes
 tags: [publishing]
 keywords: themes, styles, colors, css
 last_updated: August 12, 2015
-summary: 
+summary: "You can choose between two different themes (one green, the other blue) for your projects. The theme CSS is stored in the CSS folder and configured in the configuration file for each project."
 ---
 {% include linkrefs.html %} 
 
-
+## Theme options
 You can choose a green or blue theme, or you can create your own. In the css folder, there are two theme files: theme-blue.css and theme-green.css. These files have the most common CSS elements extracted in their own CSS file. Just change the hex colors to the ones you want.
 
 In the configuration file, specify the theme file you want the output to use — for example, `theme_file: theme-green.css`.
 
+## Theme differences
 The differences between the themes is fairly minimal. The main navigation bar, sidebar, buttons, and heading colors change color. That's about it. 
 
 In a more sophisticated theming approach, you could use Sass files to generate rules based on options set in a data file, but I kept things simple here.

doc_top_navigation.md

@@ -11,8 +11,8 @@ summary: "The top navigation provides either single links or a drop-down menu. T
 
 The top navigation reads from the \_data/topnav_doc.yml file. There are two *separate* sections:
 
-* `topnav``
-* `topnav_dropdowns``
+* `topnav`
+* `topnav_dropdowns`
 
 Items in the `topnav` section are rendered as single links. In contrast, items in the `topnav_dropdowns` section are rendered as a drop-down menu.
 
@@ -29,7 +29,7 @@ It's common to publish multiple sites. If you want to link them together, you co
 Included in the topnav.html file is an include to /doc/customMenu.html. The code there is as follows:
 
 ```
-  <li {% if site.audience == "writers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../doc_writers/{{site.suffix}}">Writer docs</a> {% else %} ../doc_writers{{page.url}}">Writer docs</a>{% endif %}</li>
+<li {% if site.audience == "writers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../doc_writers/{{site.suffix}}">Writer docs</a> {% else %} ../doc_writers{{page.url}}">Writer docs</a>{% endif %}</li>
 
 <li {% if site.audience == "designers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../doc_designers/{{site.suffix}}">Designer doc</a> {% else %} ../doc_designers{{page.url}}">Designer docs</a>{% endif %}</li>
 ```

doc_troubleshooting.md

@@ -3,7 +3,7 @@ title: Troubleshooting
 tags: [getting-started]
 keywords: trouble, problems, support, error messages, problems, failure, error, #fail
 last_updated: August 12, 2015
-summary: 
+summary: "This page lists common errors and the steps needed to troubleshoot them."
 ---
 {% include linkrefs.html %} 
 

doc_video_embeds.md

@@ -3,11 +3,12 @@ title: Video embeds
 tags: [formatting]
 keywords: videos, youtube, vimeo, video js, video wrapper, mp4, stream
 last_updated: August 12, 2015
-summary: 
+summary: "You can embed files with a Video JS wrapper by adding 'video: true' in the frontmatter. Alternatively, you can just fall back on the default video wrapper in the browser."
 video: true
 ---
 {% include linkrefs.html %} 
 
+## About Video JS
 The theme has the [video.js](http://www.videojs.com/) player integrated. But the scripts only appear on a page or post if you have certain frontmatter in that page or post. If you want to embed a video in a page and use the Video JS player, add `video: true` in your frontmatter of a page or post, and then add code like this where you want the video to appear:
 
 ```html

doc_webstorm_text_editor.md

@@ -3,9 +3,10 @@ title: WebStorm Text editor
 keywords: webstorm, sublime, markdown, atom, gnome, notepad ++, textpad, bbedit
 tags: [getting-started]
 last_updated: August 12, 2015
-summary:
+summary: "You can use a variety of text editors when working with a Jekyll project. WebStorm from IntelliJ offers a lot of project-specific features, such as find and replace, that make it ideal for working with tech comm projects."
 ---
 
+## About text editors and WebStorm
 There are a variety of text editors available, but I like WebStorm the best because it groups files into projects, which makes it easy to find all instances of a text string, to do find and replace operations across the project, and more.
 
 If you decide to use WebStorm, here are a few tips on configuring the editor.