https://DevOpsCloud.io -- Cloud Monk Losang Jinpa

Return to Cloud Monk's Package Manager Book, Glossaries, Technical Writing, Technical Writing Bibliography, Writing Bibliography, Writing, Writing Topics, Awesome Tech Writing

Technical Writing Glossary

• active voice. The voice used to indicate that the subject of a sentence is directly performing the action expressed by the verb.

Agile. A software development methodology based on iterative and incremental development.

Ajax. (Asynchronous JavaScript and XML) A method of combining interactive applications such as JavaScript, dynamic HTML, XML, CSS, and others on a web page.

API. (Application Programming Interface) An interface that enables one program to interact with another.

application. Software that lets a user perform a particular task or set of tasks.

ascenders. The highest part of a character in a typeface.

ASCII. ASCII (American Standard Code for Information Interchange) is one of the oldest methods for encoding characters for use in computers. It contains 128 characters, including the English alphabet, punctuation, and other characters. Most text processing programs no longer use ASCII, instead they use Unicode, which includes the ASCII characters, but can also handle nearly all human languages. See Unicode.

assistive technology. Software or devices designed to be used by people with disabilities.

• backlog. Prioritized list of requirements used in the Agile development process.

baseline. The line upon which the letters of a typeface “sit.” The bottom of an “x” is typically on the baseline.

best practices. A method or technique that has consistently shown superior results and is often used as a benchmark.

bitmap. An image file, sometimes called a raster file, that is made of pixels. See raster file.

build (software). The process of compiling source code to turn it into finished software that runs on a computer.

burnout. A state of physical, emotional, and mental exhaustion, sometimes marked by apathy or resentment, usually caused by long-term work situations that are stressful and demanding.

• C, C++. Programming languages.

callout. A caption that contains a pointer to an area of interest.

change bar. A vertical bar in the margin of a document that indicates where content is different.

Cascading Style Sheet. See CSS.

conditional text. Text within a document that is intended to appear in some versions of the document, but not others.

consultant. An independent worker who is hired by a company to solve a particular problem.

content reuse. The management of content by breaking it into small enough components, or topics, so that each topic can be used in the appropriate place.

context-sensitive. Directly related to the nearby content. When describing help, this means that the help relates to a specific area of a web page. See also page-sensitive.

contractor. A temporary worker who is hired to work on a specific project or set of projects, for a specified amount of time.

copyright. The exclusive ownership, protected by law, of a literary work or other work of art. The copyright confers the right to make use of the work.

cross-functional. Consisting of individuals from more than one organizational unit or function.

cross-platform. Used on different operating systems.

CSS. Cascading Style Sheet, a language for specifying how a web page is presented.

• descenders. The lowest part of a character in a typeface.

design document. Document that describes how the product works, and describes the product architecture.

development process. The process a company goes through to take its product from concept to finished work. See also SDLC.

DITA. (Darwin Information Typing Architecture) An XML schema for authoring and publishing topic-oriented content.

DocBook. An XML schema for authoring and publishing technical documentation.

documentation. any content (written, illustrated, or both) supporting the use, operation, maintenance, or design of a product or service.

documentation plan. A specification that describes what a document or set of documentation will consist of and what its schedule is.

domain expert. Subject matter expert in a specific field or endeavor. In high tech, this generally refers to knowledge in a field other than software.

draft. Any iteration of a document before it is finalized.

DTD. (Document Type Definition) A schema language used to define the elements, attributes, and structure of an XML-based language.

• ebook. An electronic book, readable on a computer or other electronic device.

end point. The state or condition that happens when a procedure reaches its natural conclusion.

end user. The person who uses a product or service (as opposed to the person who buys it, manages it, or designs it).

enterprise software. Software used in business or government as opposed to that used by individuals.

escalation path. The escalating steps a customer takes when trouble occurs, starting with a proposed solution for the problem, and ending with a call to the company for assistance if the solutions don’t work.

external facing. Materials that are meant to be seen by customers and others outside the organization.

extranet. A portion of an organization’s internal network that is accessible to a controlled set of outside users, such as customers or vendors, but not to the general public.

• FAQ. (Frequently Asked Questions) A set of basic questions and their answers about a specific topic or product.

flush. Aligned, as in type.

font. A single size and style of a particular typeface, although in the digital world, “font” is typically used to refer to any typeface. See typeface.

freeze. The point in development where all activity stops.

• gerund. A verb form that acts as a noun, ending in “-ing.”

glossary (translation). A company-specific list of words and their accepted translation into different languages.

grid. An invisible structure of horizontal and vertical lines that defines where elements go on a web page or document page.

• hard copy. Documentation printed on paper; the opposite of electronic, or “soft copy.”

help authoring tool (HAT). Program used to write and generate online help

heuristic evaluation. Expert review of a user interface or product against standard usability best practices

HLDD (High-Level Design Document). A document that describes the software architecture and how the software works. See also LLDD.

hover. Movement of the mouse pointer over an icon or link, without clicking a button, that causes a change to the application. See mouseover.

HTML. Hypertext Markup Language, the code that uses tags to tell web browsers how to display content.

human factors. A discipline of study, sometimes called ergonomics, that involves the study of the way humans react with their environment.

• imperative mood. The form of a verb that makes a direct command.

infinitive. Verb form that shows no person, or tense. Usually the “to” form of the verb, although the imperative mood also uses the infinitive without “to.” See also imperative mood.

informational interview. An interview that is conducted by a would-be employee for the purpose of collecting information rather than seeking a job.

internal facing. Materials that are meant to be seen only by people within the organization.

IT. Information Technology (pronounced “Eye-Tee”).

• Java. a programming language designed for Internet development.

JavaScript. A programming language that is used mainly to create dynamic, interactive web pages.

JIRA. An issue-tracking system.

justified type. Type that is aligned straight on both the left and right sides.

• knowledge base. A centralized repository of information, from which internal and external users seek help.

• landing page. See splash page.

layers. In image editing, additional drawing areas that can be overlaid on one another to add greater control. A layer can be used to add text to an image. Layers can also be hidden or shown to allow a single image file to be generated in many different ways.

leading. The vertical space between lines of text.

Linux. (Pronounced “Linnucks”) A UNIX-like operating system designed to provide UNIX capabilities at low cost or free.

LLDD (Low-Level Design Document). A document that describes the software architecture and how the software works in more detail than a HLDD. See also HLDD.

localization. The act of changing content so that it is relevant to the locale.

locator (in indexing). The part of the index entry that takes the user to the target. It can be a page number, a range of page numbers, or a pointer to a different index entry. Also called reference. See also reference.

lorem ipsum. Dummy content made up of Latin text, used by designers to indicate text in a layout.

• mailing list. An email discussion group.

marcomm. Marketing Communications, the messages and media used to interact with customers.

marker (in indexing). An indicator that the marked word or term belongs in the index.

metrics. A set of measurements by which performance can be assessed.

milestone. An important action or event on a timeline.

monospaced font. A font in which all characters use up the same amount of space. A lowercase “i” takes the same amount of space as a capital “M.”

mouseover. Movement of the mouse pointer over an icon or link, without clicking a button, that causes a change to the application. See hover.

MRD (Marketing Requirements Document). A document that describes what a product must include to meet customer needs.

• NOC (Network Operations Center). Data center where a company’s servers and networking equipment are located.

• online help. Task-oriented modules (sometimes called assistive documentation) that come up when a user clicks a Help link or icon on a software application or web page.

open source software. Software whose source code is openly shared with and among developers and users.

outdent. A line that extends outside of the normal margin.

out-of-the-box experience . (OOBE) The impression a user has when first opening a package and setting up the product.

• page-sensitive. Used to refer to help that relates to the information on a single page. See also context-sensitive.

passive voice. The voice used to indicate that the subject of a sentence is the recipient of the action expressed by the verb.

PDF. (Portable Document Format) A file format originally created by Adobe Systems that provides an electronic image of text and graphics that looks like a printed document.

peer editing. Editing done by a colleague of equal standing.

person. In writing, a way to indicate how near the reader or writer is to what is being said. The first person is “I,” “me,” or “we.” The second person is “you.” The third person is “he,” “she,” “it,” “they,” or “them.”

personas. Fictional characters designed to represent the target users of a given product.

placeholder. A substitute piece of text or graphic used temporarily in place of the real thing.

point. A measurement that equals 1/72 of an inch, used to measure type sizes.

PRD (Product Requirements Document). A document that defines a product and the features it must have.

procedure. Numbered steps that guide a user through a process.

product manager. The person responsible for selecting and determining the features of a product and overseeing it as it goes through development.

proofreading. The process of reviewing and correcting content for typos, grammar errors, and stylistic issues.

proprietary. Belonging to someone or something that has exclusive rights of ownership.

• QA (Quality Assurance). A system process of testing to determine that a product or service meets specifications.

quick start. A short document that is designed to get the user immediately up and running.

• ragged. A typography term meaning there is no straight alignment. The text in this book is flush left, ragged right.

raster file. An image file, sometimes called a bitmap, that is made of pixels. See bitmap.

README. A file that accompanies software and is intended to be read first.

redundant pairs. Words that people tend to put together out of habit but one word is unneeded.

reference (in indexing). Also called locator, the part of the index entry that takes the user to the target. It can be a page number, a range of page numbers, or a pointer to a different index entry. See also locator.

requirements. The features and functionality that are needed in a particular release of a product.

roadmap. In high-tech, a product development plan that matches goals with technology solutions.

run book. Set of written procedures for operation of the system or network by an administrator or operator.

• sandbox. An environment in which a person can try out software to see how it works.

sans serif. Typeface without serifs. (See serif.)

screen shot. An image recording of a portion of the information on the computer screen.

scrum. An Agile development method based on defined development periods called sprints. See also Agile. See also sprints.

SDLC (Software Development Life Cycle). Project management model that describes the software development stages. See also development process.

search engine optimization (SEO). The process of improving a website’s visibility so more visitors come to it.

second person. Designation of the person to whom you are speaking as the subject: “You.”

Section 508. An amendment to the US Rehabilitation Act to require federal agencies to make electronic and information technology accessible to people with disabilities.

self-help. A customer’s ability to access knowledge base to find information, thus avoiding calls to Customer Support.

sentence case. A way of capitalizing that uses capital letters for the first word and all proper nouns in the segment.

serial comma. A comma that precedes the final item in a list. (Also known as the Oxford comma.)

serif. Short cross-line at the end of the main strokes of a letter in a typeface like Times, Palatino, or Georgia.

server. A computer that manages network resources.

Simplified Technical English. A controlled language used primarily in aerospace maintenance documentation.

single-sourcing. Developing content with the intent of producing all or parts of it, in multiple formats.

SME. See subject matter expert.

social media. The use of web-based and mobile technology to create interactive dialog.

specification. Document that defines what a product or application does.

splash page. Initial web page (sometimes called landing page) that acts as an introduction to the rest of the site.

sprint. In the Agile scrum development method, a unit between a week and a month during which the development team works on a defined set of features and functionality.

SQL. Structured Query Language. A programming language used to manage or access data in a relational database.

stakeholder. A person that has an interest in a specific project or business activity.

standup meeting. Short, usually daily, status meeting with members of an Agile scrum team.

stet. A proofreading mark that means “Don’t change this.”

structured content. Content that has been classified using metadata (data that describes other data).

structured authoring. Writing that follows the enforcement of organizational structure of content components.

subject (in indexing). The word, phrase, or abbreviation listed in alphabetical order in the index. Also called topic. See also topic.

subject matter expert (SME). The person who knows about a specific aspect of technology. See also domain expert.

surrogate user. In usability testing, a participant who has the characteristics and business needs of the customer to whom the product is targeted.

• technical writer. Someone who conveys information about a technical subject, directed at a specific audience for a specific purpose.

template. A preformatted file that is used to create other documents.

tense. In grammar, the time of action (present, past, or future).

third person. Designation of a person other than yourself or the one you are speaking to, with pronouns like he, she, they, or them.

time to market. The length of time from the beginning of product development to its availability for customer delivery.

title case. A way of capitalizing that applies capital letters to the first and last words of a title and all nouns, pronouns, adjectives, verbs, adverbs, and subordinating conjunctions. See also sentence case.

topic (in indexing). The word, phrase, or abbreviation listed in alphabetical order in the index. Also called subject. See also subject.

topic-oriented writing. Writing intended for reuse. Each topic is a unit of information that stands alone, or can be mixed and match with other units. See also content reuse.

translation memory. a database of text segments that have been translated.

trigger. In a procedure, the event that starts procedure.

typeface. A single set of characters..

troubleshooting. The act of investigating the cause of problems.

• Unicode. A standard for encoding text for use in computers. Unicode supports most of the world’s writing systems. See ASCII. See UTF-8.

UNIX. An operating system widely used in workstations and servers.

usability. The ease of use with which a human being interacts with a product; the act of taking physical and psychological requirements of human beings into account during the design process.

use case. A description of a system’s behavior in response to user actions.

user-centered design. Iterative design tested with surrogate customers until the majority of test subjects succeed at completing the intended tasks.

user experience. (UX) The entire interaction a person has with a product, system, or service. User Experience professionals focus on improving the usability of a product.

user-friendly. Easy to learn and use.

user interface. (UI) The set of commands through which a human being interacts with a computer; typically, a graphical interface with windows, icons, and menus.

user stories. In a scrum process, short statements about what the user does with the product. See also scrum.

UTF-8. A mapping method for representing Unicode characters that is widely used in text processing and web applications. UTF-8 is compatible with ASCII. See ASCII. See Unicode.

UX. See user experience

• vector file. A graphic file made of lines and points, which can be enlarged and reduced without losing data.

voice. A grammatical term that describes how the subject and verb in a sentence related to each other. See active voice and passive voice.

• Waterfall. A software development process in which development is done sequentially. Contrast with Agile

web server. A computer that “serves up” web content to a browser.

web services. Machine-to-machine interaction over a network

WFH. Acronym for “working from home.”

white paper. A document (like a report) that states a position or helps to solve a problem. White papers are often written in a style that is part way between marketing language and technical language.

white space. The negative space on a page.

wiki. A collaborative website that can be modified quickly by many users.

workaround. A solution that enables a user to “work around” a problem rather than fixing the problem.

workflow. A set of tasks and steps that make up a work process.

work for hire. A work created by one person and paid for (and thus owned) by another (the employer).

• x-height. The height of a basic lowercase letter in a typeface, such as the height of an “x.”

XML. (eXtensible Markup Language) A metalanguage (language used to describe or analyze language) that is used to define other languages. See DITA. See DocBook.

XML schema. A formal description of what an XML document can contain.

Fair Use Sources:

• writing on DuckDuckGo