Major edits (#10)

* Minor edit to resources (adds Git for docs link)

* Adjust sidebar styles

* Adding theme/common for cross-theme content

* Point the Hyde head for asciidoctor.css to theme/common/

* Add docx lock file to ignore

* Add several new terms to glossary

* Add 'contributing' tag

* Major revisions and additions

Author: briandominick

.gitignore

@@ -9,3 +9,4 @@ scripts/cibuild
 presentations/
 _notes/
 blog/
+*.docx#

_config/jekyll.yml

@@ -16,6 +16,7 @@ layouts_dir:  _build/theme/hyde/_layouts
 images_dir:   assets/images
 includes_dir: theme/hyde/_includes
 css_dir:      theme/hyde/css
+theme_common_dir: theme/common
 
 asciidoc: {}
 asciidoctor:

_data/glossary.yml

@@ -7,9 +7,13 @@ terms:
 
   - term: AsciiDoc
     definition: |
-      An extensible lightweight markup language with numerous powerful features such as conditional processing, file includes, and variable text substitutions.
+      An extensible, dynamic lightweight markup language with numerous powerful features such as conditional processing, file includes, and variable text substitutions.
       Pronounced _ASK-ee-doc_.
 
+  - term: binary files
+    definition: |
+      Complex files consisting of bytecode, often representing archives of flat files and opaque to most source-control systems.
+
   - term: CCO
     definition: |
       See *complex content object*.
@@ -19,33 +23,89 @@ terms:
       Command-line interface.
       Any place where a command prompt expects textual input.
       Pronounced _C-L-I_.
-# tag::cco-example[]
+
+  - term: commit
+    definition: |
+      A defined set of changes made to the source code of a project managed by source control.
+      In Git, you organize source changes into commits as a way of organizing contributions to the codebase.
+      Anyone who makes commits to the project is a _committer_.
+
   - term: complex content object
     definition: |
       Abbreviated CCO, this is an item that may be more metadata than content, stored many to a file, as opposed to more typical text content units like chapters or topics, which may have some metadata but are mainly text and images.
       See <<chapter-managing-complexity>>.
 
+  - term: dependency, software
+    definition: |
+      A separate software product that is required for the development or operation of another application.
+      These are either prerequisites that need to be set up or packages that are integrated automatically, but the main software relies on them to perform some crtical task.
+
+  - term: deprecation
+    definition: |
+      The process of designating product features for cessation of support.
+      Whenever an existing feature is slated to be disabled in a future release, providers notify users the functionality will cease.
+      This flagging is the actual act of deprecation.
+      Actual removal or cessation of support is a separate operation.
+# tag::cco-example[]
+  - term: DevOps
+    definition: |
+      An approach to software development that seeks to optimize complementarity between product coding and build/test procedures, mainly through automation and continuous integration.
+
   - term: DITA
     definition: |
       Acronym for _Darwin Information Typing System_.
       An XML standard designed for technical writing, introduced by IBM in 2005.
       In addition to a markup standard, DITA incorporates dynamic functionality and mature framework elements.
       https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture[Wikipedia].
 
+  - term: DocBook
+    definition: |
+      An XML-based structured semantic markup language designed to convey technical information.
+      Founded on Usenet in 1991, DocBook was originally popularized as the basis for O'Reilly technical books.
+      AsciiDoc was designed as a lightweight writing format to be preprocessed into DocBook XML.
+
   - term: DRY
     definition: |
       For "don't repeat yourself", referring to a single-sourcing approach to code or docs.
 # end::cco-example[]
+  - term: dynamism (in CMSes)
+    definition: |
+      At a minimum, a content management system is _dynamic_ if it enables the setting of variables for tokenized substitution inside parsed content.
+      That is, users can embed references to outside data or content inside preprocessed source, which will be populated by that outside data or content, depending on which external content is established as the _value_ of any given _key_ (token).
+      Other elements of dynamism may include conditional processing, which is often necessary for the proper establishment and processing of variables.
+
+  - term: extensibility
+    definition: |
+      Software that offers users the prerogative to heavily alter or add to its performance or abilities is considered “extensible”.
+
+  - term: flat files
+    definition: |
+      Simple files consisting only of textual characters and easily readable by source-control systems.
+
+  - term: framework
+    definition: |
+      A set of digital assets as well as structural and methodological conventions designed to enable rapid programming that is accessible to anyone familiar with the framework.
+      Frameworks use standardized files, namespaces, architectures, and coding principles to enforce conventionality in style while enabling developers to jumpstart (“bootstrap”) their own projects as well as parachute into others' with minimal orientation to the codebase.
+
   - term: FOSS
     definition: |
       Acronym for _free, open source software_.
-      “Free” here implies both free as in do what you want with it, and free as in no money need be exchanged.
+      “Free” here implies both free as in do pretty much whatever you want with it, and free as in no money need be exchanged.
 
   - term: JSON
     definition: |
       A very common format for semi-structured data, popular for data transfer, especially with JavaScript/Node.js, though quickly becoming the industry standard.
       Pronounced _JAY-sahn_.
 
+  - term: linter
+    definition: |
+      A utility that scans text or code for syntactically, grammatically, or vocabularily incorrect content to flag or reject.
+
+  - term: literal (expression)
+    definition: |
+      Text in technical documentation that conveys actual code or values.
+      Literals are usually represented by monospace type to distinguish it as directly expressing practical data or code.
+
   - term: Markdown
     definition: |
       One of the lightest weight and most popular textual markup languages, popularized on GitHub, StackOverflow, various forums and comments systems, and numerous other places.
@@ -58,34 +118,94 @@ terms:
 
   - term: IDE
     definition: |
-      For _integrated development environment_, a toolchain/platform that facilitates software programming in a customized context that incorporates the particularities of the source language(s) and the product build.
+      For _integrated development environment_, a toolchain/platform that facilitates software programming in a customized context that incorporates the particularities of the source language(s), any specific configuration for a given project, and elements of the product build procedure.
       Pronounced _I-D-E_.
 
+  - term: open source
+    definition: |
+      Software source code that is specifically licensed for sharing, usually with some restrictions.
+      See also, FOSS.
+
+  - term: platform
+    definition: |
+      Any configurable software product that enables one or more users to contribute customized data or content for routine processing using a controlled, predictable environment.
+
+  - term: RDB
+    definition: |
+      Abbreviation for _relational database_.
+
+  - term: regression testing
+    definition: |
+      QA to ensure that changes in a new version of a software product work as intended with previous configurations, integrations, and applications.
+      Thorough integration testing ensures all still-supported features and functionality remain backward compatible.
+
+  - term: relational database
+    definition: |
+      A complex, multi-table data source that is structured according to a defined schema and primarily accessed using queries.
+      As opposed to flat files, RDBs are almost always stored as binary files and therefore opaque to most source control systems.
+
+  - term: release cycle
+    definition: |
+      The full set of procedures involved in planning and distributing a version of a software product.
+      The release cycle includes planning, coding, testing, packaging, distributing, and any other tasks involved in turning software from a set of ideas to a new edition for production use.
+
+  - term: repository, code
+    definition: |
+      A file-storage system for _source code_, which tracks metadata about the code files and tracks changes across user-established _versions_.
+      Commonly referred to as a “repo”.
+
   - term: REST API
     definition: |
       An API (see <<glossary-api,API>>) that listens for and responds to HTTP requests to established endpoints.
+      A “RESTful” service waits for an HTTP client request, such as a _POST_, _GET_, or _DELETE_ transaction at a specific URI, enabling third-party developers to build applications to interact with that service based on documented functionality and permissable formats for exchanging data.
+      (REST stands for “Representational State Transfer”, which I had long-since forgotten before I just looked it up, because it is never used.)
       Pronounced _REST A-P-I_.
 
   - term: reStructuredText
     definition: |
       A dynamic lightweight markup language associated with Python development.
+      Abbreviated _RST_.
 
   - term: RST
     definition: |
-      Abbreviation for reStructuredText.
+      Abbreviation for _reStructuredText_.
 
   - term: SaaS
     definition: |
       Acronym for _software as a service_. Subscription-licensed tools hosted in “the cloud”, SaaS products require no user maintenance and provide thin-client remote access (e.g., browsers, mobile apps).
       Relevant examples include Wordpress.com, GitHub, Slack, and Office 365.
       Pronounced _sass_.
 
+  - term: small data
+    definition: |
+      Datasets that are limited in count and complexity.
+      Small data can be stored in flat files, with or without schematic constraints.
+      Distinguished more in terms of the subjects of data suitable for such storage systems, namely recordsets of limited volume.
+      Similar to Big Data, small data structures usually support nested attributes represented by flat formats like XML, JSON, and YAML.
+
   - term: SME
     definition: |
       Subject matter expert.
       Someone close to or highly familiar with the source/product who contributes this expertise to the documentation process.
       Please don't pronounce this _sme_ or for god's sake _shme_.
 
+  - term: source code
+    definition: |
+      Human readable programming instructions intended to be compiled into machine code.
+
+  - term: stack
+    definition: |
+      The particular set of software utilities or languages used in developing and/or running a software product.
+      My technical documentation stack includes Ruby, AsciiDoc, YAML, Asciidoctor, and Jekyll.
+      See also _tooling_.
+
+  - term: tooling
+    definition: |
+      Software utilities configured to provide routine services.
+      For documentarians, tooling includes text editors and any utilities that generate and package documentation files.
+      A _toolchain_ is a specific set of technologies used to perform a given complex procedure, such as writing and building documentation.
+      See also _stack_.
+
   - term: topic
     definition: |
       A discrete content item intended to be included (embedded or referenced) in parent document.
@@ -100,6 +220,21 @@ terms:
       Initialism for _user interface_.
       Pronounced _U-I_.
 
+  - term: Unicode
+    definition: |
+      A collection of universally standardized character sets that incorporate massively extended non-Western alphabets and extended symbolic characters.
+      The most common is UTF-8, which incorporates characters consisting of between one and four 8-bit bytes.
+
+  - term: UX
+    definition: |
+      Initialism for _user experience, the study of overall interactions between users and a product.
+      Pronounced _U-X_.
+
+  - term: workflow
+    definition: |
+      The procedures involved in fulfilling a task or project.
+      Workflows may be formal, as in a prescribed set of protocols, or they informal, as in a description of what actually happens within a team or workspace.
+
   - term: XML
     definition: |
       Extensible markup language, a tag-based means of conveying semi-structured data.

assets/images/screenshot_atom-codewriting-subdirs.png

@@ -1,4 +1,3 @@
-[[contributing]]
 = Collaborative Authorship & Lean Publishing
 
 This book is an experiment, and you are invited to partake.

assets/images/screenshot_file-structure-docx-archive.png

@@ -2,7 +2,7 @@
 = Resources
 
 This is a curated page of resources helpful to exploring and implementing a docs-as-code approach to technical documentation.
-You are strongly encouraged to submit a pull request including your own favorites!
+You are strongly encouraged to submit a merge request including your own favorites!
 
 == Source Control
 
@@ -15,6 +15,9 @@ I wish I had read this series when I was first learning Git.
 
 === Git
 
+* https://www.cuttlesoft.com/using-git-software-documentation/[Using Git to Manage Software Documentation]
+This overview of Git from a documentarian's perspective might be a good palce to start.
+
 * http://www.codeschool.com/courses/try-git[CodeSchool's Try Git tutorial]
 
 * http://gitimmersion.com/lab_01.html[Git Immersion] +
@@ -51,6 +54,25 @@ A compilation of excellent blog posts examining intermediate and advanced topics
 
 === MarkDown
 
+== DITA
+
+* http://www.dita-ot.org/1.8/dev_ref/extending-the-ot.html[DITA Open Toolkit] +
+I list this extensible, open-source DITA toolkit up front because it is most valuable here as an option for DevOps engineers trying to integrate DITA into their product source control or build infrastructure.
+This is the place for hackers to start.
+
+
+
+== Regular Expressions (RegEx)
+
+Following up on <<chapter-coding-regex>>, let's explore some RegEx tools and tutorials.
+
+* link:https://regexone.com/[RegexOne] is a great tutorial
+
+* The site link:http://www.rexegg.com/[RexEgg.com] offers some very cool instructionals and in-depth explorations.
+
+* link:https://regexr.com/[Regxr] is a great “fiddle”-style tool for running experiments against test patterns with lots of resources a click away.
+
+
 == SSG: Static Site Generators
 
 === Jekyll
@@ -70,6 +92,16 @@ With my limited programming acumen, I find Ruby difficult to learn, though even
 That said, these tools are all truly excellent, and there are a great many resources on Ruby, especially on https://stackoverflow.com/tags/ruby/info[StackOverflow], which is a pretty good place to start learning Ruby, and _the_ place to go when you get stuck.
 ****
 
+=== Minuteman
+
+=== Hugo
+
+=== Awestruct
+
+* http://awestruct.org/[Awestruct site]
+
+* https://github.com/awestruct/awestruct/[source code]
+
 == Conversion and Migration Tools
 
 === Pandoc
@@ -82,9 +114,7 @@ Short of such programmatic applications, you can explore Pandoc simply by conver
 * http://pandoc.org/[pandoc.org]
 *  https://publishing.sfu.ca/2013/11/building-publishing-workflows-with-pandoc-and-git/[Building Publishing Workflows with Pandoc and Git] (blog entry)
 
-=== Swagger
-
-=== Doxygen
+=== Tilt
 
 === Other Conversion/Migration Tools
 
@@ -100,6 +130,12 @@ This hacky-to-install but well-documented tool will convert your Google Docs han
 
 * https://github.com/lmmx/gdocs2md-html[GitHub repo]
 
+== API Docs Generators
+
+=== About OpenAPI
+
+=== Doxygen
+
 == CCMS: Component Content Management Systems
 
 Here's where things start to get hairy.
@@ -150,7 +186,7 @@ LeanPub is a great way for authors to self-publish; it includes an e-commerce sy
 * link:https://leanpub.com[Leanpub site]
 
 [TIP]
-Don't see your favorite platform here? Suggest it in the Issues for this GitHub project or in the
+Don't see your favorite platform here? Suggest it in the link:https://github.com/briandominick/codewriting/issues[Issues] for this GitHub project, or add it directly and issue a merge request.
 
 == Blogs
 
@@ -181,5 +217,15 @@ Though not particularly docs-as-code oriented, this site occasionally features d
 
 * link:http://thecontentwrangler.com/[The Content Wrangler]
 
+== Forums
+
+Write the Docs::
++
+While not docs-as-code exclusive, the Write the Docs community is where you'll find the most forward-thinking documentarians.
+Their conferences, meetups, and Slack channels are the place to mine peers and experts for their experience and advice.
++
+* link:http://www.writethedocs.org[Website]
+* link:http://www.writethedocs.org/slack/[Write the Docs Slack workspace]
+
 [[resources-git-tooling]]
 == Git Tooling

book-cw/backmatter/contributing.adoc

@@ -1,14 +1,16 @@
 = Acknowledgements
 
-My first shout out has to go to Eric Sammer, CTO at Rocana, who had the foresight to set me up with such a great documentation toolchain.
-Eric has given me room to experiment with the docs at Rocana, just as he and the Engineering organization have kept a constant flow of new challenges streaming across my desk.
-I did not take this job with any semblance of a notion that I was stumbling into a nascent (niché) field that so fully fuses writing and development.
+I must first express appreciation for Eric Sammer, CTO at Rocana, who had the foresight to set me up with such a great documentation toolchain.
+Eric gave me room to experiment with the docs at Rocana, just as he and the Engineering organization kept a constant flow of new challenges streaming across my desk.
+I did not take that job with any semblance of a notion that I was stumbling into a nascent (niche) field that so fully fuses writing and development.
 Since those are the only two consistent interests on my resumé, I suspect Eric saw more than I evidently did.
 
-I also want to express appreciation for my manager, Arthur Foelsche.
+I also want to express appreciation for my direct manager at Rocana, Arthur Foelsche.
 When your company is so small you're the only tech writer, it helps a lot to have somebody who's well paid to feign an interest in what you do all day.
-Truthfully: through countless hours of coding and conversation, Arthur has pushed and helped me to solve more than a few of the problems I'm truly excellent at raising.
-He also encouraged me to do this book and pursue the initiatives and projects that inspired it, as did everyone in Rocana's Engineering department.
+Truthfully: through countless hours of coding and conversation, Arthur pushed and even directly helped me to solve more than a few of the problems I'm truly excellent at raising.
+He also encouraged me to do this book and pursue the initiatives and projects that inspired it, as did so many of my colleagues there.
+
+I hope the Codewriting project serves as an unexpected, lasting artifact of all our days solving “impossible” problems together as Rocana.
 
 == Contributors