Update concept docs for spf13 review

content/concept.md

@@ -20,10 +20,10 @@ The claims made in this document are largely *empirical* and pulled from two maj
 * My experience starting 18 months ago as a new Hugo user.
 * Conversations with fellow Hugo users and noted trends within the [Discussion Forum][forum].
 
-I am submitting these changes because I have been given [explicit permission to do so](https://discuss.gohugo.io/t/roadmap-to-hugo-v1-0/2278/34). Project kickoff was in November 2016 as a result of [this forum thread on a proposed source re-organization](https://discuss.gohugo.io/t/proposed-source-organization-for-hugo-docs-concept/4506). See also [this Discuss thread from @bep re: a new restructure and redesign](https://discuss.gohugo.io/t/documentation-restructure-and-design/1891/10).
+I am submitting these changes because I have been given [explicit permission to do so](https://discuss.gohugo.io/t/roadmap-to-hugo-v1-0/2278/34). Project kickoff was in November 2016 as a result of [this forum thread on a proposed source re-organization](https://discuss.gohugo.io/t/proposed-source-organization-for-hugo-docs-concept/4506). See also [this forum thread from @bep re: a new restructure and redesign](https://discuss.gohugo.io/t/documentation-restructure-and-design/1891/10).
 
 {{% note "What is this document, Ryan?" %}}
-At the bottom of this document is a section that starts with the [most important questions for the Hugo team](#ideal-workflow) and continues with a very high-level description of an *ideal* content strategy process. This has only been included to provide insight for those unfamiliar with basic content strategy..
+At the bottom of this document is a section that starts with the [most important questions for the Hugo team](#ideal-workflow) and continues with a very high-level description of an *ideal* content strategy process. This has only been included to provide insight for those unfamiliar with basic content strategy.
 {{% /note %}}
 
 {{% warning "Disclaimer" %}}
@@ -41,16 +41,16 @@ Additionally, current Hugo documentation
 * is confusing for new users
 * is a common complaint in the Hugo forums ([forum discussion 1][ex1], [forum discussion 2][ex2])
 * lacks structure and is therefore
-    * unscalable, as demonstrated by patch pages (e.g. [here][patch1] and [here][patch2]) that seem out of place, require unnecessary drill-down, or duplicate content in other areas of the docs, thus requiring duplicative efforts to keep updated
+    * unscalable, as demonstrated by patch pages that seem out of place, require unnecessary drill-down, or duplicate content in other areas of the docs, thus requiring duplicative efforts to keep updated (e.g. ["Taxonomy Templates"][patch1] and ["Using _index.md"][patch2])
     * inconsistent in its terminology, style, and (sometimes) layout
-    * limited in effective use of Algolia's document search (i.e., due to redundant content grouping, headings, etc)
+    * limited in leveraging Algolia's document search (i.e., due to redundant content grouping, headings, etc)
     * difficult to optimize for external search engines (SEO)
-* does not leverage Hugo's more powerful features (e.g., only *one* archetype); leveraging these features would help address the aforementioned shortcomings (i.e., scalability, consistency, and search)
+* does not leverage Hugo's more powerful features (e.g., only *one* archetype); inclusion of these features (aka "dogfooding") would help address the aforementioned shortcomings concerning scalability, consistency, and search
-* assumes a higher level of Golang proficiency than is realistic for newcomers to static site generators or general web development; a prime example is the sparsity of basic and advanced code samples for templating functions, some of which may still be wholly undocumented
+* assumes a higher level of Golang proficiency than is realistic for newcomers to static site generators or general web development; a prime example is the sparsity of basic and advanced code samples for templating functions, some of which are wholly undocumented
 * lacks well-defined contribution and editorial guidelines for those interested in submitting or editing documentation
 * is not up to date
-* often unusable on smart phones or other mobile devices
+* often unusable on mobile devices
-* needs reworking of its URL structure to represent a more intuitive mental model for end users ([Discuss][ds1])
+* needs reworking of its URL structure to represent a more intuitive mental model for end users ([see this related forum thread][ds1])
 
 ### Goals
 
@@ -59,17 +59,18 @@ New Hugo documentation should...
 * reduce confusion surrounding core Hugo concepts; e.g., `list`, `section`, `page`, `kind`, and `content type` with the intention of
     * making it easier for new users to get up and running
     * creating better consistency and scalability for Hugo-dependent projects (viz., [themes.gohugo.io][hugothemes])
-    * reducing the frequency of beginner-level questions in the [Hugo Discussion Forum][forum]
+    * reducing the frequency of beginner-level questions in the [Hugo Forums][forum]
 * not require, or assume, any degree of Golang proficiency from end users;
     * that said, Hugo can—and *should*—act as a bridge for users interested in learning Golang. An implemented example of this strategic point is the inclusion of `godocref:` as a default front matter field for all function and template pages. See [`archetypes/functions.md`][functionarchetype].
 * be easiest to expand and edit for *contributors** but even easier to understand by *end users*
-     * if you don't make it *very easy* for authors to contribute to documentation correctly, they will inevitably contribute *incorrectly*;
+    * Note the following content management axioms:
-        * content modeling is king
+        * If you don't make it *very easy* for authors to contribute to documentation correctly, they will inevitably contribute *incorrectly*.
-        * go DRY (e.g., via shortcodes)
+        * Content modeling is king
-        * set required metadata (e.g., via section-specific *archetypes*)
+        * Go DRY (e.g., via shortcodes)
-        * develop contribution guidelines for both development *and* documentation
+        * Set required metadata (e.g., via section-specific *archetypes*)
+        * Develop contribution guidelines for both development *and* documentation
 * be equally accessible via mobile, tablet, desktop, and offline.
-* avoid "miscellaneous" sections (e.g.,"Extras"); [these catch-all sections are the last place end users look to get up and running](https://discuss.gohugo.io/t/site-with-different-lists-of-sections/5536/3)
+* avoid "miscellaneous" sections (e.g.,"Extras"); these catch-all sections are the last place end users look to get up and running. [See the related forum thread](https://discuss.gohugo.io/t/site-with-different-lists-of-sections/5536/3)
     * all content in miscellaneous sections should be edited and incorporated into more logical content groupings with the goal of removing miscellaneous sections entirely.
 * easily scaffold for potential *i18n/multilingual versions*.
 
@@ -87,18 +88,18 @@ This is far from an inadequate persona exercise, but I think it helped my mental
 
 #### End User: SSG Developer
 
-The SSG developer has
+The SSG Developer has
 
 * basic proficiency in Git and DVCS
-* no to little proficiency in Golang
+* little to no proficiency in Golang
 * working proficiency in front-end development---HTML, CSS, JS---but not necessarily front-end build tools
-* basic familiarity with at least one double-curly templating language (e.g., liquid, Twig, Swig, or Django)
+* basic familiarity with at least one double-curly templating language (e.g., liquid, Twig, Swig, Handlebars, or Jinja)
 * proficiency in the English language for the current version of the documentation
     * proficiency in other languages (for future multilingual versions)
 
 #### End User: Themes (i.e. blogger/author/hobbyist)
 
-The themes end user has
+The Themes End User has
 
 * limited proficiency in the command line/prompt
 * proficiency in one of the [supported content formats](https://hugodocsconcept.netlify.com/content-management/formats/)(specifically markdown)
@@ -159,11 +160,11 @@ The following are high-level requirements for the documentation site.
 
 ## UX/UI
 
-- [X] Copyable and/or downloadable code blocks (via highlight.js and clipboard.js, extended for hugo-specific keywords); see [this specific request from @bep for this feature](https://discuss.gohugo.io/t/proposed-source-organization-for-hugo-docs-concept/4506/10?u=rdwatters)
+- [X] Copyable and/or downloadable code blocks (via highlight.js and clipboard.js, the former of which should be extended for hugo-specific keywords); see [this specific request from @bep for this feature](https://discuss.gohugo.io/t/proposed-source-organization-for-hugo-docs-concept/4506/10?u=rdwatters)
 - [X] Dual in-page navigation (i.e. site nav *and* in-page TOC)
 - [X] Smooth scrolling
 - [X] [RTD-style admonitions][admonitions] (see [example admonition shortcode](https://github.com/rdwatters/hugo-docs-concept/blob/master/layouts/shortcodes/note.html) and [examples on published site](/contribute/documentation/#admonition-short-codes))
-- [ ] Share buttons: Reddit, Twitter, LinkedIn, and "Copy Page Url"; the last of these provides the strongest utility for docs references in the Hugo forums
+- [ ] Share buttons: Reddit, Twitter, LinkedIn, and "Copy Page Url"; the last of these provides the strongest utility for docs references in the Hugo forums. See the [GH issue for Share Buttons](https://github.com/rdwatters/hugo-docs-concept/issues/2)
 
 ## Author Experience (AX)
 
@@ -207,37 +208,36 @@ This is no longer a site navigation link and is instead a button along with "Fil
 
 ### Site Showcase
 
-Site showcase has stayed more or less as is, including styling, etc. However...
+Site Showcase has stayed more or less as is, including styling, etc. However...
- * The showcase archetype has been refined for simplicity and now has new [contribution guidelines](/contribute/documentation).
+ * The showcase archetype has been refined for simplicity and has new [contribution guidelines](/contribute/documentation).
- * To keep compatibility, all [showcase content files][showcasefiles] have been edited to reflect the new content type. This will also be updated in the ["docs" page of the contribute section](/contribute/documentation/)
+ * To keep compatibility, all [showcase content files][showcasefiles] have been edited to reflect the new content type. This has also be updated in the ["docs" page of the contribute section](/contribute/documentation/)
 
 ### Press & Articles
 
 * The press and article pages have been moved under "News" along with "Release Notes". This section is lower on the navigation because it's less frequently visited than other areas (my assumption).
-* Like everything else, I've kept up with changes to the docs upstream on GitHub, but in this case, I also included a [half dozen *new* articles as well](/news/press-and-articles/).
+* Like everything else, I've kept up with changes to the docs upstream on GitHub, but in this case, I also included a [half dozen *new* articles as well](/news/press-and-articles/). For good measure, I [submitted a PR](https://github.com/spf13/hugo/pull/3175) for the existing repo as well.
 
 ### About Hugo
 
-* Content is more or less the same, but I've cleaned up a lot of the language, and copy edited for consistency throughout. I've also added in some extra frills (e.g. resources that extoll and teach more about the benefits of SSGs on [/about/benefits](/about/benefits/)).
+* Content is more or less the same, but I've copy edited for consistency throughout. I've also added in some extra frills (e.g. resources extolling and [the benefits of SSGs](/about/benefits/)).
 * Release notes are now in the "News" section, although I'm still unsure on this decision. I can gladly move this back into "About" to give it a higher degree of discoverability in the menu.
 
 ### Getting Started
 
 * **[[UPDATE 2017-03-12]]**
-    * The Quick Start needs to be completely reworked; this could include a walkthrough of a new default theme (#)
+    * The Quick Start needs to be completely reworked; this could include a walkthrough of a new default theme. [See the GH issues in the POC repo](https://github.com/rdwatters/hugo-docs-concept/issues/17)
 * ~~The [Quick Start][] has been completely updated for more consistent heading structure, etc. Also, **I may delete the "deployment" section of the Quick Start** since this a) adds unnecessary length, making the guide less "quick" and b) detracts from the new "hosting and deployment" section, which offers better advice, and c) is redundant with [Hosting on Github](https://hugodocsconcept.netlify.com/hosting-and-deployment/hosting-on-github/). For example, the Quick Start didn't mention that files already written to public are not necessarily erased at build time. This can cause problems with drafts. I think the other options—e.g. Arjen's Wercker tutorial—are more viable and represent better practices for newcomers to Hugo. If future versions of Hugo include baked-in deployment features, I think it's worth reconsidering adding the deployment step back to the Quick Start.~~
 
 ### Content
 
 * This section has been renamed "Content Management" to facilitate elimination of the ["extras"](http://gohugo.io) section. **Note**: this section does *not* include any templating. The convention is `content-management/concept.md` (for explanation and usage) `templates/concept-templates.md` (for examples, functions, etc), and then `variables/concept-variables.md`.
-    * That said, I'm working on refactoring a series of shortcodes for variables so that it's only a matter of referencing them once and having them update everywhere.
+    * That said, I'm working on refactoring a series of shortcodes for variables so that it's only a matter of referencing them once and having them update everywhere. As of 2017-03-13, these live in `content/readfiles`.
 
 ### Themes
 
 Themes section organization has only changed slightly in that the 6 content pages have been consolidated to just 4.
 
 * "Installing a theme" and "Using a Theme" have been combined since one largely dovetails with the other. The current [using a theme page](http://gohugo.io/themes/usage/) is pretty skimpy. An alias for `themes/usage` has been set up accordingly.
-*
 
 ### Templates
 
@@ -246,14 +246,12 @@ Themes section organization has only changed slightly in that the 6 content page
     * Go template primer
     * Lookup order
     * Base templates
-    * Hugo Lists (introduces the lists concept [i.e. sections, taxonomies, etc]); this includes one of multiple forthcoming visualizations for Hugo architecture
+    * [Hugo Lists page](https://hugodocs.info/templates/lists) that first introduces the lists concept (i.e. sections, taxonomies, etc) before some well-ordered templating examples. This new page includes one of multiple forthcoming visualizations for Hugo architecture (2017-03-13: the current version is pretty ugly).
-    * Rendering Hugo Lists (i.e., ordering, grouping, etc)
+* Shortcodes and menus (templating), pagination, data, traversing local files, data-driven content, and data files have all moved out from "Extras" and into templating. *Note that there is only one stylesheet in the local files templating example now*.
-* Shortcodes and menus (templating), pagination, data, traversing local files, data-driven content, and data files have all moved out from "Extras" and into templating. *Note that there is only one stylesheet in the local example now*..
-* **2017-02-26**. I am currently working on a new example for `readDir`.
 
 ### Taxonomies
 
-*Taxonomies* is no longer an independent section. Similar to shortcodes and menus, taxonomies is broken into two equal pages: one under Content Management, and the other under Templates.
+*Taxonomies* is no longer an independent section. Similar to shortcodes and menus, taxonomies is broken into three pages for content management, templating, and variables.
 
 
 ### Extras
@@ -262,19 +260,19 @@ Themes section organization has only changed slightly in that the 6 content page
     * *Extras*, in the content world, is the equivalent of *miscellaneous* or *additional resources*. It's an area that's been tacked onto site navigation to accommodate a *seemingly* disparate set of new features. In other words, READ: "We don't have any idea of where to put this"
 * *Extras* pages:
     * Aliases. Incorporated into [URL Management](/content-management/urls/)
-    * Analytics. Incorporated into [built-in partials](/templates/partials/#using-hugos-built-in-partials)
+    * Analytics. Incorporated into [internal templates](/templates/internal/)
     * Builders. This has been removed completely since it has no real added value. The three "builders" mentioned (`new site`, `new theme`, and `new <content>`) are all well-delimited in their respective pages, which is where end users expect to find this type of information in the first place.
-    * Comments. Incorporated into [content management](/content-management/comments/) for content-related pieces and mentioned in [partials](/templates/partials/) for implementation.
+    * Comments. Incorporated into [content management](/content-management/comments/) for content-related pieces and mentioned in [internal templates](/templates/internal/) for implementation.
-    * Cross-References. Added as its own page under Content Management (`/content-management/cross-references/`)
+    * Cross-References. Added as its own page under Content Management (`/content-management/cross-references/`). Highlighted functions also have their own respective function pages (see the [Function Quick Reference](/functions/))
     * Custom robots.txt. Incorporated into [/templates/robots/](/templates/robots/)
-    * Data Files and Data-Driven Content. Combined and incorporated into [/templates/data-templates/](/templates/data-templates/)
+    * Data Files and Data-Driven Content. Combined and incorporated into [/templates/data-templates/](/templates/data-templates/). When I first started working with Hugo, I found the distinction between the two pages to be very counter-intuitive.
     * GitInfo. Incorporated into [/variables/git/](/variables/git/)
     * LiveReload. This doesn't really merits its own page. It's mentioned in features, usage, about, and elsewhere.
     * Menus. This is broken into [/content-management/menus/](/content-management/menus/) and [/templates/menu-templates/](/templates/menu-templates/)
     * Pagination. Now in [/templates/pagination/](/templates/pagination/)
     * Permalinks. Now a heading/subsection of [/content-management/urls/](/content-management/urls/
     * Scratch. Has it's own devoted function page at [/functions/scratch/](/functions/scratch/), and is therefore in the [Functions Quick Reference](/functions/). Also mentioned in an admonition in [/variables/page/](/variables/page/).
-    * Shortcodes. Now split into two pages, one a [/content-management/shortcodes/](/content-management/shortcodes/) and the templating portion (i.e. "create your own shortcodes") at [/templates/shortcode-templates/]
+    * Shortcodes. Now split into two pages, one at [/content-management/shortcodes/](/content-management/shortcodes/) and the templating portion (i.e. "create your own shortcodes") at [/templates/shortcode-templates/]
     * URLS. Now combined with permalinks and others as a heading/subsection of [/content-management/urls/](/content-management/urls/)
     * Syntax Highlighting. The shortcode is featured and explained with usage examples at [/content-management/shortcodes/](/content-management/shortcodes/), as well as expaned upon in it's own page under [/tools/syntax-highlighting/](/tools/syntax-highlighting/). I did this under the assumption that *developers* are most interested in adding code blocks to their content.
     * Table of Contents. This is now it's own page under [/content-management/toc](/content-management/toc/) and referenced in [/variables/page-variables](/variables/page/).
@@ -284,22 +282,22 @@ Themes section organization has only changed slightly in that the 6 content page
 
 The "Community" section has been removed as a site navigation item because `/contribute` is now it's own section.
     * There are now more calls than ever for contributing to Hugo throughout the Hugo docs.
-    * The most important changes to "Community" (now [/contribute/](/contribute/)) are that @digitalcraftsman's tutorial on contributing to Hugo can be found under [/contribute/development/](/contribute/development/), and a brand-new page for *contributing to documentation*, including examples of shortcodes used throughout the docs, etc, can be found at [/contribute/documentation/]. This is a **VERY IMPORTANT* change since it's instructions, archetypes, and guidelines like this that will make the documentation site scale more easily.
+    * The most important changes to "Community" (now [/contribute/](/contribute/)) are that @digitalcraftsman's tutorial on contributing to Hugo can be found under [/contribute/development/](/contribute/development/), and a brand-new page for *contributing to documentation*, including examples of shortcodes used throughout the docs, etc, can be found at [/contribute/documentation/]. This is an important change since its instructions, archetypes, and guidelines like this that will make the documentation site scale more easily.
 
 ### Tutorials
 
-* Original page: <http://gohugo.io/tutorials>
+* **[[Update 2017-03-12]]** "Tutorials" as a site section has been completely removed. The remaining three articles: 1. Creating a Multilingual Site, 2. Creating a New Theme, and 3. Migrate from Jekyll to Hugo were a) duplicative, b) outdated, or c) contradictory to other areas of the documentation (specifically w/r/t Hugo-specific terms). Full-length tutorials can be a very difficult thing to maintain within a docs site.  I'd offer that it's better to provide examples and explanations throughout the documentation and then allow the community to publish their own tutorials (i.e., with links to the tutorials on the Articles Page).
-* All installation guides have been consolidated under [/getting-started/installing/](/getting-started/installing/)
+* ~~Original page: <http://gohugo.io/tutorials>~~
-    * Why? Installing Hugo shouldn't be considered a separate tutorial
+* ~~All installation guides have been consolidated under [/getting-started/installing/](/getting-started/installing/)~~
-    * "Tutorials" is not an intuitive place for end users to look for this kind of documentation
+    * ~~Why? Installing Hugo shouldn't be considered a separate tutorial~~
-* All content moved from `/tutorials` has been edited to reflect a less tutorial-ish style of language (e.g., removal of lines starting with "In this tutorial...")
+    * ~~"Tutorials" is not an intuitive place for end users to look for this kind of documentation~~
-* Aliases added to new pages and in-page links updated throughout
+* ~~All content moved from `/tutorials` has been edited to reflect a less tutorial-ish style of language (e.g., removal of lines starting with "In this tutorial...")~~
-* Remaining Tutorials
+* ~~Aliases added to new pages and in-page links updated throughout~~
-    * Are these worth keeping in their entirety if they reflect (sometimes much) older versions of Hugo?
+* ~~Remaining Tutorials~~
-    * Michael Henderson's "Creating a Theme" website ([current][],[concept][]) has been copy edited and content edited to include the new code block shortcodes. Michael did an *amazing* job with this tutorial, and it must have taken him *forever*, but much of the information included in the tutorial is now spread throughout the documentation in more appropriate places. Also, because this is an older tutorial, some of the paradigms aren't quite as up to date.
+    * ~~Are these worth keeping in their entirety if they reflect (sometimes much) older versions of Hugo?~~
-    * Rick Cogley's still needs to be copy edited a bit, but overall looks good. That said, this tutorial was put together before Hugo began implementing it's international features.
+    * ~~Michael Henderson's "Creating a Theme" website ([current][],[concept][]) has been copy edited and content edited to include the new code block shortcodes. Michael did an *amazing* job with this tutorial, and it must have taken him *forever*, but much of the information included in the tutorial is now spread throughout the documentation in more appropriate places. Also, because this is an older tutorial, some of the paradigms aren't quite as up to date.~~
-* **Guidelines for New Tutorials**
+    * ~~Rick Cogley's still needs to be copy edited a bit, but overall looks good. That said, this tutorial was put together before Hugo began implementing it's international features.~~
-    * **[[Update 2017-03-12]]** "Tutorials" as a site section has been completely removed. The remaining three articles: 1. Creating a Multilingual Site, 2. Creating a New Theme, and 3. Migrate from Jekyll to Hugo were a) duplicative, b) outdated, or c) contradictory (specifically w/r/t Hugo-specific terms). Full-length tutorials can be a very difficult thing to maintain within documentation; it's my position that it's better to provide examples and explanations throughout the documentation and then allow the community to publish their own tutorials (i.e., with links to the tutorials on the Articles Page).
+* ~~**Guidelines for New Tutorials**~~
     * ~~To keep the content in tutorials maintainable, it's important to set standards on what should be contained within said tutorials when published directly to the Hugo docs. (Of course, listing beginning-to-end tutorials in other areas of the website [i.e., press and articles] is a very good idea). The following pieces of information should be omitted from full-text tutorials in the Hugo docs because they are better delimited and kept current in other areas:~~
         * ~~Explanations directory structure or content organization~~
         * ~~Explanations of content formats (namely, `.md`) or front matter~~
@@ -310,6 +308,7 @@ The "Community" section has been removed as a site navigation item because `/con
 
 * This section still only contains the same two troubleshooting content pages from the current site.
     * Both pages have been copy edited, and the markdown has been cleaned up for consistency.
+    * 2013-03-12. Per [this suggestion from @moorereason]()
 
 ### Tools
 
@@ -320,7 +319,7 @@ The "Community" section has been removed as a site navigation item because `/con
     * Frontends. Same frontends material previously under "tools." Copy edited for consistency.
     * Editor Plug-ins. Same editor plug-ins material found in current documentation. Copy edited for consistency.
     * Search. Same search material under "tools" in current documentation. Copy edited for consistency.
-    * Other projects. This might be worth restructuring since I'm not a fan of catch-all sections or pages.
+    * Other projects. This might be worth restructuring since I'm not a fan of catch-all sections or pages. Similar to the previous "Tutorials" section, this could also be a matter of scope creep on what the docs can and should contain. My opinion is that too many SERP-like pages offer little to end users who are likely coming to the docs for very different reasons.
 
 ### Hugo Cmd Reference
 
@@ -513,9 +512,9 @@ The following demonstrates the *ideal* sequence for content strategy and is only
 If the Hugo Team finds the improvements to the Hugo documentation acceptable, I've proposed the following schedule for releasing the new Hugo documentation.
 
 1. **2017-02-27** Release to Gitter Channel for dev review
-2. **2017-03-05** Post in Discussion Forum for Hugo user feedback
+2. **2017-03-11** Post in Discussion Forum for Hugo user feedback
-3. **2017-03-6** Pull request/add to Hugo Rep
+3. **2017-03-20** Pull request/add to Hugo Rep
-3. **2017-??-??** Add to Hugo repo for release with v19?
+3. **2017-??-??** Add to Hugo repo for release with v20, currently scheduled for 2017-03-27.
 
 [^1]: At this point, not too much of the URL structure has changed that considerably. I've been fastidious about adding aliases wherever possible and trying to retain URLs whenever still applicable. That said, the [current list of aliases is quite large](/contribute/documentation/#be-mindful-of-aliases).