DocOps Jargon

Write The Docs, a conference that brings everyone who writes the docs together in the same room.

For application programming interface, an intentional framework by which third-party developers can enable their own programs to integrate with a product. Pronounced A-P-I. See also REST API.

A limited set of characters that form the US English lowest-common denominator. Asciidoctor processes non-ASCII-encoded files, but only ASCII characters are required in AsciiDoc markup.

An extensible, dynamic lightweight markup language with numerous powerful features such as conditional processing, file includes, and variable text substitutions. Pronounced ASK-ee-doc.

A currently maintained suite of open-source utilities made for converting and otherwise working with the AsciiDoc markup language. Asciidoctor is operated by volunteers on a non-profit organization advocating, developing, and supporting AsciiDoc.

Complex files consisting of bytecode, often representing archives of flat files and opaque to most source-control systems.

See complex content object.

Command-line interface. Any place where a command prompt expects textual input. Pronounced C-L-I.

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.

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].

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.

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.

An approach to software development that seeks to optimize complementarity between product coding and build/test procedures, mainly through automation and continuous integration.

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. Wikipedia.

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.

For "don’t repeat yourself", referring to a single-sourcing approach to code or docs.

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.

Software that offers users the prerogative to heavily alter or add to its performance or abilities is considered “extensible”.

Simple files consisting only of textual characters and easily readable by source-control systems.

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.

Acronym for free, open source software. “Free” here implies both free as in do pretty much whatever you want with it, and free as in no money need be exchanged.

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.

A utility that scans text or code for syntactically, grammatically, or vocabularily incorrect content to flag or reject.

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.

One of the lightest weight and most popular textual markup languages, popularized on GitHub, StackOverflow, various forums and comments systems, and numerous other places. Markdown, however, is not a dynamic language.

Acronym for graphical user interface. Pronounced GOO-ee.

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.

Software source code that is specifically licensed for sharing, usually with some restrictions. See also, FOSS.

A data object that consists of a key (name) and a value (content). Also called key-value pairs, the value may be a string or a number, or it maye be a more complex data object. The value might also be another parameter containing another object, or the direct value may be an array or structure.

Any configurable software product that enables one or more users to contribute customized data or content for routine processing using a controlled, predictable environment.

Abbreviation for relational database.

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.

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.

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.

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”.

An API (see 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.

A dynamic lightweight markup language associated with Python development. Abbreviated RST.

Abbreviation for reStructuredText.

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.

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.

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.

Human readable programming instructions intended to be compiled into machine code.

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.

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.

A discrete content item intended to be included (embedded or referenced) in parent document. See [topic-based-authoring].

Initialism for quality assurance.

Initialism for user interface. Pronounced U-I.

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.

Initialism for user experience, the study of overall interactions between users and a product. Pronounced U-X.

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.

Extensible markup language, a tag-based means of conveying semi-structured data.

A highly configurable and extensible means of formatting, stylizing, and conveying XML data.

A format for semi-structured data. Usually preferred over JSON and XML when human reading and writing is called for, but lacking a standard means of schematizing templates. Pronounced YAM-el.