More on landing

Author: agentlecisco

_learn/07-evaluating-ssg-themes.md

@@ -6,20 +6,24 @@ image:
   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.
+Themes for static site generators often provide the advanced user experience features such as navigation, search, and responsive designs for mobile consumption. 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.
+When researching and selecting a theme, analyze the possibilities for printed outputs, such as PDF or EPUB. Perhaps you need version control for both the output and the source files. The size of your site may mean you need to consider performance gains you can make with the build. 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.
 
 ## Admonitions or notes
 Are there designs for output of levels of admonition, such as warning, information, and note?
 
+Advanced admonitions can enable substituting custom text instead of "Note" or "Warning," or custom icons. You can also configure the admonitions in some themes to expand or contract in-page. For example, look at the variations for Markdown source with the [Mkdocs Material theme when using the admonition extension](https://squidfunk.github.io/mkdocs-material/extensions/admonition/). Or, when using [RST with the Read the Docs theme, you have lots of directives](https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/demo.html#admonitions) to choose from, including Attention, Hint, Important, Note, Tip, Error, or Danger, or write your own. You should also test if code blocks work within an admonition if that is important in your documentation.
+
+![Note, Tip, Error, oh my](/images/learn/rtd-admonitions.png)
+
 ## Code syntax and highlighting
-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?
+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? What about the behavior of the scroll bar for long lines of code examples? Are there line numbers available? Can you highlight or emphasize certain lines to convey meaning? How about captions on the code block, similar to captions on figures?
 
-## Comment engines
-Which comment engines are supported? Do they work with what other organizations use in your company or group?
+## Comments or forums integration
+Which comment engines are supported? Do they work with the comment systems 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.
@@ -33,11 +37,17 @@ When translations are available, are they simple to get to? Does the theme itsel
 ## Navigation and configuration possibilities
 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?
 
+Do you want to have Previous and Next buttons on each page, so that someone can go through a series of pages in order?
+
 ## Responsive and mobile design
 Does the theme use thoughtful navigation and search when on a small screen?
 
+Can your readers get to the Contents fairly easily and expand and contract, even when on a mobile phone or tablet? Check how the search experience works when using a smaller screen. Most of the built-into-the-browser developer tool kits, such as the Chrome Developer Tool, lets you preview the site experience on a simulated smaller screen.
+
+![](/images/learn/rtd-mobile-nav.png)
+
 ## Search
-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?
+Is the search form in a prominent location and if needed, can you customize the them to place the search form somewhere else 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 page?

book/index.md

@@ -5,18 +5,20 @@ excerpt: "Docs Like Code book in print and ebook. Paperback now available on Ama
 last_modified_at: Sat May 13 08:43:14 CDT 2017
 ---
 
-<img src="../../images/docs-like-code-book.jpg" alt="Docs Like Code" style="padding:14px;" align="right" height="200" width="319">
 
-<h1>About the book</h1>
+<h1>Get Started with Docs as Code</h1>
+
+<img src="../../images/docs-like-code-book.jpg" alt="Docs Like Code" style="padding:14px;" align="right" height="200" width="319">
 <p>We've transformed the way teams work together on docs, and we want to show you the best practices for writing docs using development tools and techniques. Now available in both print and ebook, check out <i>Docs Like Code</i>.</p>
 
+
 <p><a href="http://www.lulu.com/spotlight/justwriteclick" style="display: inline-block;
   margin-bottom: 20px;
   padding: 8px 20px;
   font-size: 14px;
-  background-color: #64baaa;
+  background-color: #fc5720;
   color: #fff;
-  border: 2px solid #64baaa !important;
+  border: 2px solid #fc5720 !important;
   border-radius: 3px;
   &:visited {
     color: #fff;
@@ -68,9 +70,9 @@ last_modified_at: Sat May 13 08:43:14 CDT 2017
   margin-bottom: 20px;
   padding: 8px 20px;
   font-size: 14px;
-  background-color: #ffc858;
+  background-color: #fc5720;
   color: #fff;
-  border: 2px solid #ffc858 !important;
+  border: 2px solid #fc5720 !important;
   border-radius: 3px;
   &:visited {
     color: #fff;
@@ -92,6 +94,6 @@ last_modified_at: Sat May 13 08:43:14 CDT 2017
 <blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">This one just moved to the top of my reading list. A book on how to treat docs like code by <a href="https://twitter.com/annegentle">@annegentle</a>. Awesome!  &gt; <a href="https://t.co/nRkSZkhv5x">https://t.co/nRkSZkhv5x</a></p>&mdash; Patrick Andriessen (@napnamPat) <a href="https://twitter.com/napnamPat/status/838695213841403904">March 6, 2017</a></blockquote>
 <script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
 
-<h1>Get the t-shirt!</h1>
+<h2>Get the t-shirt!</h2>
 
 <a href="http://just-write-click.myshopify.com/">Now available - Docs Like Code t-shirts</a>!