Merge pull request #102 from justwriteclick/articles

Articles - three evaluation tutorials

Author: annegentle

_posts/10-evaluating-ssg-themes.md _learn/07-evaluating-ssg-themes.md_posts/10-evaluating-ssg-themes.md renamed to _learn/07-evaluating-ssg-themes.md

@@ -1,11 +1,13 @@
 ---
 title: "Evaluating Static Site Generator themes"
 image:
-  path: /images/so-simple-sample-image-4.jpg
-  thumbnail: /images/site-logo.png
+  path: /images/learn/ssg-themes.png
+  thumbnail: /images/learn/ssg-themes400x225.png
 ---
 
-Themes for static site generators often provide the advanced user experience features such as search. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables. What about printed outputs, such as PDF? Or versions for the output and the source? Any performance gains you can make with the builds themselves? Themes are one part of this analysis.
+Themes for static site generators often provide the advanced user experience features such as search. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables.
+
+What about printed outputs, such as PDF? Or versions for the output and the source? Any performance gains you can make with the builds themselves? Themes are one part of this analysis.
 
 Here's a short list of questions you may want to ask about the theme you use for a static site generator.
 
@@ -16,7 +18,7 @@ Are there designs for output of levels of admonition, such as warning, informati
 For code examples, can you set the exact highlight you want to use, such as JavaScript or Python or Bash? Does the code snippet have a copy icon for copying only the code and not copying a prompt?
 
 ## Comment engines
-Which comment engines are supported and do they work with what other organizations use in your company or group?
+Which comment engines are supported? Do they work with what other organizations use in your company or group?
 
 ## Customization
 How straightforward is it to add your logo or a header that's common to multiple web sites? Can you learn how to maintain the theme's customizations yourself or will you need to rely on a web developer for maintenance and any enhancements such as adding a version drop-down list? For example, the Jekyll theme "Minimal Mistakes" is "skinnable," meaning you can [configure various color variations](https://mmistakes.github.io/minimal-mistakes/docs/configuration/) for that theme.
@@ -28,7 +30,7 @@ Are images automatically resized when looking at them on a mobile browser or res
 When translations are available, are they simple to get to? Does the theme itself have the ability to be localized, such as for the search form or navigation elements, can the labels used in the theme be localized?
 
 ## Navigation and configuration possibilities
-Does the theme have a sidebar, breadcrumbs, and an in-page table of contents? Can you turn on or off each based on the page layout or page template or whether the person is using a mobile browser or tablet?
+Does the theme have a sidebar, breadcrumbs, and an in-page table of contents  available? Can you turn on or off each based on the page layout or page template or whether the person is using a mobile browser or tablet?
 
 ## Responsive and mobile design
 Does the theme use thoughtful navigation and search when on a small screen?
@@ -37,12 +39,12 @@ Does the theme use thoughtful navigation and search when on a small screen?
 Is the search form in a prominent location and if needed, can you move the search form on the page? Does the search work on mobile devices with readable results? Can the result list also be styled?
 
 ## Social media support
-If you want Twitter cards for your documentation pages, are they available through the theme? Which social media sites can you link to from each documentation page?
+If you want Twitter cards for your documentation pages, are they available through the theme? Which social media sites can you link to from each page?
 
 ## Tables
 Do tables work on different browsers? If PDF or epub is another output option, do the tables still work on a particular page size or do you need to adjust how tables are made in the source file itself for good results in the output?
 
-## Theme Updates
+## Theme updates
 How easy is it to upgrade the theme files? Can you make regular updates through a version-control system and know exactly which theme you have in use?
 
 ## Versions

_posts/11-evaluating-table-layouts.md _learn/08-evaluating-table-layouts.md_posts/11-evaluating-table-layouts.md renamed to _learn/08-evaluating-table-layouts.md

@@ -1,10 +1,12 @@
 ---
 title: "Evaluating table layouts and formatting"
 image:
-  path: /images/so-simple-sample-image-4.jpg
-  thumbnail: /images/site-logo.png
+  path: /images/learn/table-layout.png
+  thumbnail: /images/learn/table-layout400x225.png
 ---
 
+Table layout can be an annoying and difficult aspect of using simple markdown as documentation source. That said, when using Markdown or RST tables you can compare changes to simple tables more easily during reviews.
+
 One of the most helpful tools when creating tables for Markdown or RST is the Tables Generator at https://www.tablesgenerator.com/markdown_tables. You can draw tables or paste table data and then render the ASCII-based output for pasting into your document source file.
 
 For example, here is an empty five-column table in Markdown, ready for you to insert cell data and spaces.

_posts/14-ssg-search-implementations.md _learn/09-ssg-search-implementations.md_posts/14-ssg-search-implementations.md renamed to _learn/09-ssg-search-implementations.md

@@ -1,8 +1,8 @@
 ---
-title: "Static Site Generator search options"
+title: "Evaluating Static Site Generator search options"
 image:
-  path: /images/so-simple-sample-image-4.jpg
-  thumbnail: /images/site-logo.png
+  path: /images/learn/ssg-search-options.png
+  thumbnail: /images/learn/ssg-search-options400x225.png
 ---
 
 Most static site generators provide a browser-side search capability, where the list of indexed keywords for search are built at the same time as the output. Learn more about considerations for each SSG in the following sections.

_posts/00-github-for-docs-files.md

@@ -12,7 +12,7 @@ Learning GitHub or any source control system backed by `git` for documentation s
 
 You can learn how to sign up for a GitHub account and pricing plans on [help.github.com](https://help.github.com/articles/signing-up-for-a-new-github-account/).
 
-You can do all these docs-as-code tutorials with a free GitHub account.
+You can do all these docs-as-code tutorials with a free GitHub account. I recommend using SSH keys rather than entering your password for each `git` command that requires authentication. Read about [Connecting to GitHub with SSH](https://help.github.com/articles/connecting-to-github-with-ssh/) in the GitHub user documentation.
 
 ## Learn basic Terminal and Git Bash commands