Technical Writing: Ontology & Knowledge Base

Technical communication employs specialized vocabulary distinguishing it from general writing and journalism. This comprehensive glossary defines essential terms, frameworks, and concepts that technical writers use daily. Understanding this ontology enables precise communication about documentation practices and facilitates professional development in the field.

Core Concepts and Definitions

Technical Communication: The discipline of conveying scientific, engineering, or technical information to specific audiences for specific purposes. Unlike creative writing, technical communication prioritizes accuracy, clarity, and utility over aesthetic expression. The Society for Technical Communication (STC) defines it as "the process of making technical information understandable and available to those who need it."

Information Architecture (IA): The structural design of shared information environments. In documentation, IA encompasses content organization, navigation systems, labeling schemes, and search functionality. Good IA enables users to find information efficiently, while poor IA creates friction regardless of content quality.

Minimalism: A documentation approach emphasizing task-focused content with minimal conceptual background. Pioneered by John Carroll at IBM, minimalism recognizes that users typically consult documentation to accomplish specific tasks rather than learn comprehensive systems. Minimalist documentation provides procedural steps with just enough context for successful completion.

Single Sourcing: The practice of creating content once and publishing it to multiple formats, channels, or products. Single sourcing eliminates redundant maintenance and ensures consistency across outputs. Implementation requires structured authoring formats that separate content from presentation.

Content Reuse: The strategic use of existing content components in multiple documentation contexts. Reuse ranges from copying paragraphs between documents to sophisticated content management systems that assemble publications from modular components. Effective reuse requires consistent terminology, style, and information architecture.

Structured Authoring and Markup

DITA (Darwin Information Typing Architecture): An XML-based architecture for authoring, producing, and delivering technical information. DITA organizes content into typed topics (concept, task, reference) with standardized markup enabling sophisticated processing and output generation. Originally developed by IBM, DITA is now an OASIS standard.

Topic-Based Authoring: An approach organizing content into discrete, self-contained units addressing specific subjects. Unlike book-oriented writing where context carries across pages, each topic must stand alone. Topics typically correspond to answerable questions: "How do I X?" (task), "What is Y?" (concept), "What are the Z parameters?" (reference).

Markdown: A lightweight markup language using plain text formatting syntax. Created by John Gruber in 2004, Markdown has become the dominant format for software documentation due to its readability and tool ecosystem. Variants include GitHub Flavored Markdown (GFM), CommonMark, and Markdown Extra.

reStructuredText (RST): An extensible markup language primarily used in Python documentation. RST provides more structural semantics than Markdown, including native support for tables of contents, cross-references, and footnotes. The Sphinx documentation generator uses RST as its primary format.

DocBook: A semantic markup language for technical documentation originally developed by HaL Computer Systems and O'Reilly & Associates. DocBook uses XML to define document structure independent of presentation, enabling output to HTML, PDF, and ePub formats from single sources.

Documentation Types and Formats

API Documentation: Technical reference describing application programming interfaces. API docs include endpoint specifications, request/response examples, authentication requirements, and error codes. Quality API documentation typically combines reference material with tutorials and interactive explorers.

README: A text file introducing a software project, typically displayed prominently in code repositories. Effective READMEs explain what the project does, why it exists, how to install it, and basic usage. The Make a README project promotes standardization.

Runbook: Operational documentation guiding IT staff through routine procedures and incident response. Runbooks originated in telecom operations and have been adopted by DevOps teams. Good runbooks include pre-conditions, step-by-step procedures, verification steps, and rollback instructions.

Knowledge Base: A centralized repository of information about a product, service, or topic. Knowledge bases typically support self-service support through search and browse interfaces. Modern knowledge bases often include community-contributed content alongside official documentation.

Release Notes: Documentation accompanying software releases describing changes, bug fixes, and known issues. Effective release notes help users understand what has changed and whether upgrading affects their workflows. Keep a Changelog promotes standardized formats.

Docs-as-Code Terminology

Docs-as-Code: An approach treating documentation with the same tools and processes as software development. Documentation resides in version control, undergoes code review, and deploys via CI/CD pipelines. This approach emerged from software teams seeking to reduce friction between code and documentation updates.

Static Site Generator (SSG): A tool that generates HTML pages from source files at build time rather than on request. Documentation SSGs like Docusaurus, MkDocs, and Hugo transform Markdown into fast, secure documentation sites suitable for hosting on CDNs.

Continuous Integration/Continuous Deployment (CI/CD): Practices automating build, test, and deployment processes. For documentation, CI/CD pipelines check for broken links, validate syntax, run linters, and publish updates automatically when changes merge to main branches.

Git: A distributed version control system enabling collaborative development (and documentation) with full history tracking. Git workflows like GitHub Flow and GitLab Flow provide patterns for review, approval, and publication that apply equally to code and documentation.

Pull Request (PR): A mechanism for proposing changes to a repository, enabling review before integration. In docs-as-code workflows, subject matter experts submit documentation changes via PRs, which technical writers review for style, clarity, and consistency.

Quality and Standards

Plain Language: A communication approach prioritizing clarity for broad audiences. Government initiatives like the U.S. Plain Writing Act of 2010 mandate clear communication in federal documents. Plain language principles include active voice, common vocabulary, logical organization, and visual design supporting comprehension.

Readability Score: A metric estimating the education level required to comprehend text. Common formulas include Flesch Reading Ease, Flesch-Kincaid Grade Level, and Gunning Fog Index. While imperfect, readability scores provide objective benchmarks for content accessibility.

Style Guide: A set of standards for writing and formatting documentation. Style guides address grammar, punctuation, capitalization, terminology, and voice. Notable examples include the Microsoft Writing Style Guide, Mailchimp Content Style Guide, and Google Developer Documentation Style Guide.

Linting: Automated analysis of text for style violations, grammar errors, and inconsistencies. Documentation linters like Vale enforce style guide compliance programmatically, catching issues that human reviewers might miss.

Accessibility (a11y): The practice of ensuring documentation can be used by people with disabilities. Web Content Accessibility Guidelines (WCAG) provide standards for color contrast, screen reader compatibility, keyboard navigation, and alternative text for images.

User Experience and Research

Information Foraging: A theory comparing information seeking to animal foraging behavior. Users "scent" information through cues like headings and links, pursuing paths that seem promising. Understanding information foraging helps writers design navigation and content structures supporting efficient discovery.

Findability: The ease with which users can locate information within a documentation set. Findability depends on information architecture, search functionality, and content metadata. Techniques improving findability include faceted navigation, tagging, and cross-linking.

Content Audit: A systematic review of existing documentation to assess quality, accuracy, and coverage. Content audits identify redundant content, gaps, outdated material, and inconsistencies. Results inform content strategy and prioritization decisions.

User Persona: A fictional representation of a user segment based on research. Personas include goals, pain points, technical proficiency, and context of use. Documentation teams use personas to prioritize content and tailor tone for specific audiences.

Card Sorting: A user research method for discovering how people categorize information. Participants organize topics into groups that make sense to them, revealing mental models that should inform information architecture. Open card sorting allows participants to create category names; closed card sorting uses predefined categories.

Emerging Concepts

AI-Assisted Writing: The use of artificial intelligence tools for content generation, editing, and optimization. Large language models can draft content, suggest improvements, translate between languages, and personalize documentation for specific user contexts.

Knowledge Graph: A network of entities and relationships representing domain knowledge. Documentation knowledge graphs connect concepts, enabling intelligent navigation and discovery beyond traditional hierarchical structures.

DocsOps: The application of DevOps principles to documentation workflows. DocsOps emphasizes automation, monitoring, and continuous improvement of documentation processes alongside product development.

Conclusion

Technical writing's vocabulary reflects its evolution from a craft to a discipline grounded in research, technology, and user-centered design. Mastering this ontology enables practitioners to communicate precisely about their work, evaluate tools and methodologies, and participate effectively in professional communities. As the field continues evolving—with AI assistance, new formats, and changing user expectations—this vocabulary will expand to capture emerging practices and concepts.