diff --git a/_data/glossary.yml b/_data/glossary.yml index f17716849..850621cea 100644 --- a/_data/glossary.yml +++ b/_data/glossary.yml @@ -1,3 +1,19 @@ +$ref_openapi: + term: $ref (OpenAPI spec) + def: "Allows the inclusion of a piece of an OpenAPI description from another location, aiding in reusability." + +accept_header: + term: Accept header + def: "Part of the HTTP specification, it indicates the types of media that the client can process. For instance, specifying Accept: application/json will let the server know that the client expects JSON data." + +acceptance_criteria: + term: acceptance criteria + def: "Specific conditions that a user story or feature must satisfy to be accepted by the product owner or stakeholders." + +accessibility_testing: + term: accessibility testing + def: "Ensuring that documentation is usable and understandable by people with disabilities, in compliance with standards like the Web Content Accessibility Guidelines (WCAG)." + agile_testing: term: agile testing def: "Relying on user feedback after release to improve docs iteratively. Risky without pre-release testing." @@ -12,7 +28,15 @@ api_blueprint: api_console: term: API Console - def: "Renders an interactive display for the RAML spec. Similar to Swagger UI, but for RAML." + def: "Renders an interactive display for the RAML spec. Similar to Swagger UI, but for RAML. See also interactive API console." + +api_contract: + term: API contract + def: "A documented agreement that specifies the behavior of the API, including endpoints, request methods, request payloads, response schemas, and more. See also OpenAPI specification document." + +api_definition: + term: API definition + def: "See API specification. This is the structured description of how the API functions, its endpoints, parameters, responses, and more. Swagger tools parse this definition to provide various functionalities." api_documentation: term: API documentation @@ -22,6 +46,10 @@ api_key: term: API key def: "A unique identifier required to authenticate API requests. API keys control access to the API." +api_gateway: + term: API gateway + def: A server that acts as an intermediary for requests, often providing features like rate limiting, logging, security measures, and more. Many modern API gateways offer built-in support for importing Swagger (OpenAPI) definitions. This allows developers to quickly deploy, manage, and monitor their APIs using the Swagger definition as a starting point." + api_portal: term: API portal def: "A developer-facing website that provides documentation, support, and access management for an API. Serves as the main interface for API consumers." @@ -34,6 +62,10 @@ api_transformer: term: API Transformer def: "A cross-platform service provided by APIMATIC that will automatically convert your specification document from one format or version to another. See apimatic.io/transformer." +api_versioning: + term: API versioning + def: "A technique to make changes to your API without breaking the contract for existing users." + apiary: term: Apiary def: "Platform that supports the full life-cycle of API design, development, and deployment. For interactive documentation, Apiary supports the API Blueprint specification, which is similar to OpenAPI or RAML but includes more Markdown elements. It also supports the OpenAPI specification now too. See apiary.io." @@ -58,18 +90,50 @@ authentication: term: authentication def: "The process of verifying the identity of a user or client making an API request. Common authentication methods include API keys, OAuth, and basic auth." +authentication_token: + term: authentication token + def: "A token used to validate the identity of the client or user making the request. Synonymous with Authorization tokens or bearers." + authorization: term: authorization def: "The process of determining what permissions an authenticated user has for different operations and resources in the API." authorization_documentation: term: authorization documentation - def: "Explains how to get API keys, showing how to authenticate requests with examples. Details error messages related to authorization issues. Notes sensitivity of keys and expiration times." + def: "Instructions and details on how users can obtain access credentials and authenticate their requests to the system. Crucial for APIs that require secure access." + +authorization_tokens_or_bearers: + term: authorization tokens or bearers + def: A type of header parameter, these are tokens used to identify and authenticate the user making the request. Commonly used with JWT (JSON Web Tokens) and OAuth. backlog: term: backlog def: "In Scrum, a prioritized list of work items or user stories waiting to be worked on and completed by the team." +backlog_grooming: + term: Backlog grooming/refinement + def: "An ongoing process where the product owner and the Scrum team review items in the backlog to ensure they are prioritized and ready for future sprints." + +base_url: + term: base URL + def: "The main part of the URL, which usually doesn't change. Parameters are then added to this base URL to access different resources or perform specific operations. Similar to endpoint." + +bearer_token: + term: Bearer token + def: "A type of access token that is passed in the header for API requests to authenticate the user. See authorization tokens or bearers." + +beta_testing: + term: beta testing + def: "Testing done by real users in their real environment before the final release. Feedback from beta testing can highlight issues in both the product and the associated documentation." + +bitbucket: + term: Bitbucket + def: "Similar to GitHub and GitLab, Bitbucket is a platform (by Atlassian) that hosts Git repositories and facilitates collaboration, version control, and often continuous integration/continuous deployment (CI/CD)." + +blame: + term: blame + def: "A Git command used to display who made the last modification to each line of a file and what that modification was." + blobr: term: Blobr def: "A cloud platform for creating API portals that package API use cases into purchasable products with customized documentation. Allows monetizing APIs." @@ -78,29 +142,64 @@ branch: term: branch def: "A copy of the Git repository that is often used for developing new features. Usually, you work in branches and then merge the branch into the master branch when you're ready to publish." +bug: + term: bug + def: "A defect or issue in the product or documentation. Bugs raised in documentation might pertain to factual inaccuracies, unclear instructions, or missing content." + +burndown_chat: + term: Burndown chart + def: "A visual representation of the work remaining in a sprint versus time. It helps teams predict when all the work will be completed." + +caching_headers: + term: caching headers + def: "Headers like ETag, Last-Modified, Cache-Control, and Expires that help control how responses are cached by the client or intermediate proxies." + +checkout: + term: checkout + def: "The process of retrieving a specific revision or branch from a repository to work on locally." + +cherry_pick: + term: cherry-pick + def: "Allows you to select a specific commit from one branch and apply it onto another branch." + clone: term: clone def: "The Git command used to copy a repository in a way that keeps it linked to the original. The first step in working with any repository is to clone the repo locally. Git is a distributed version control system, so everyone working in it has a local copy (clone) on their machines." code_sample: term: code sample - def: "A snippet of code that shows how to use an API. Code samples demonstrate API usage in real programming languages." + def: "Practical, executable examples in various programming languages that show how to use specific features or accomplish tasks with the product." commit: term: commit def: "A snapshot of your changes to the Git repo. Git saves the commit as a snapshot in time that you can revert to later if needed. You commit your changes before pulling from origin or before merging your branch within another branch." -components: - term: components +components_openapi: + term: components (OpenAPI spec) def: "Storage for re-usable schema definitions referenced elsewhere through $ref pointers in the OpenAPI specification." conceptual_docs: term: conceptual docs - def: "High-level overview documentation that teaches developers how to use an API through tutorials, guides, and explanations of key concepts." + def: "Explains foundational ideas, giving readers a sense of the bigger picture. Guides users in understanding the underlying principles and concepts of the technology or product." +content_type_header: + term: Content-Type header + def: "Part of the HTTP specification, it's used to indicate the type of data contained in the body of the message, whether it's in an HTTP request or response. It allows the client or server to interpret how the data should be processed." + +component_content_management_system: + term: Component content management system (CCMS) + def: "A type of content management system (CMS) that manages content at a granular level, rather than as entire documents or pages. In a CCMS, content is broken down into smaller, reusable components or chunks, such as paragraphs, sentences, or even individual words. These components can be independently managed, edited, and reused across multiple documents or outputs. A CCMS is especially useful in environments where content is frequently repurposed or where consistency and efficiency are paramount, such as in technical documentation or large-scale publishing operations." + +content_management_system: + term: Content management system (CMS) + def: "Systems like WordPress or Drupal which, while not strictly docs-as-code, can be used to manage and serve documentation." continuous_delivery: term: continuous delivery - def: "Automating the build and deployment of documentation whenever content is pushed to a repository, through services like GitHub Pages or Netlify." + def: "Synonymous for Continuous Integration/Continuous Deployment (CI/CD)." + +continuous_integration_continuous_delivery: + term: "Continuous Integration/Continuous Deployment (CI/CD)" + def: "Automation practices where changes to code are automatically tested and deployed. Useful for constantly updating documentation sites." cross_reference: term: cross-reference @@ -142,17 +241,45 @@ docs_as_code: term: docs-as-code def: "Treating documentation files like code by using lightweight markup, version control, plain text editors, and engineering tools/workflows. Facilitates developer contributions." +documentation_pipeline: + term: documentation pipeline + def: "The automated process that transforms raw source content, often in Markdown or other formats, into a live documentation site." + +documentation_theme: + term: documentation theme + def: "A predefined set of styles, layouts, and behaviors applied to documentation generated by static site generators or documentation tools." + endpoint: term: endpoint - def: "The URL path that is used to make requests and receive responses from an API. The endpoints indicate how you access the resource, while the method indicates the allowed interactions (such as GET, POST, or DELETE) with the resource. The same resource usually has a variety of related endpoints, each with different paths and methods but returning different information about the same resource." + def: "The specific address (URL) where an API can be accessed. It's combined with the HTTP method to define the operations available. The endpoints indicate how you access the resource, while the method indicates the allowed interactions (such as GET, POST, or DELETE) with the resource. The same resource usually has a variety of related endpoints, each with different paths and methods but returning different information about the same resource. Similar to base url." epic: term: epic def: "A large user story that can be broken down into smaller stories, used in Agile software development to group related functionality." +error_message: + term: error message + def: "A descriptive message accompanying error status codes to provide more context on the nature of the error." + error_message_documentation: term: error message documentation - def: "Documentation about custom codes beyond standard HTTP codes. Explains codes to assist troubleshooting and error recovery. Provides actionable steps users can take to resolve issues." + def: "Explanations for potential errors users might encounter, offering solutions or workarounds to address these issues." + +externaldocs_openapi: + term: externalDocs (OpenAPI spec) + def: "Links to external documentation, providing more in-depth information or context about the API or specific endpoints." + +feedback_loop: + term: feedback loop + def: "A process for continuously gathering and integrating feedback into documentation, typically using comments, surveys, or direct user input." + +fork: + term: fork + def: "A personal copy of another user's repository. This allows one to experiment with changes without affecting the original project." + +frontmatter: + term: frontmatter + def: "Metadata at the beginning of a Markdown or other lightweight markup language file. Typically written in YAML and defines site-specific attributes." get: term: GET @@ -160,7 +287,7 @@ get: getting_started_tutorial: term: getting started tutorial - def: "An introductory guide that walks through making a basic successful call to the API and receiving a response, to get started quickly." + def: "A beginner's guide aimed at helping users achieve their first success with the product or technology. Simplifies the initial experience and encourages deeper exploration." git_repo: term: Git repo @@ -170,14 +297,38 @@ git: term: Git def: "A distributed version control system that tracks changes to code or text files. Allows branching and merging of file updates among multiple collaborators. Core part of collaborating on software projects and docs-as-code workflows." +git_hook: + term: Git hook + def: "Scripts that can run automatically on occurrence of specific events in a Git repository. They can be useful for automating certain tasks like code checks." + github: term: GitHub def: "A web-based platform built around Git that provides user interfaces and collaboration features such as wikis, issue tracking, and pull requests. Commonly used to manage documentation." +gitlab: + term: GitLab + def: "Similar to GitHub and Bitbucket, GitLab is a platform that hosts Git repositories and facilitates collaboration, version control, and often continuous integration/continuous deployment (CI/CD)." + +glossary: + term: glossary + def: "A glossary or list defining special terms, abbreviations, or jargon used in the documentation. Helps to standardize understanding and ensure clarity. See also Terminology." + +graphql: + term: GraphQL + def: A query language and runtime for APIs, allowing clients to request only the data they need. + hat: term: HAT def: "Help Authoring Tool. Refers to the traditional help authoring tools (RoboHelp, Flare, Author-it, etc.) used by technical writers for documentation. Tooling for API docs tends to use docs-as-code tools more than HATs." +head: + term: HEAD + def: "A pointer/reference to the latest commit in the branch you're currently on." + +headers: + term: headers + def: "Metadata sent with both API requests and responses. Headers can include information about the type of content being sent, authorization details, and more." + hateos: term: HATEOS def: "Stands for Hypermedia as the Engine of Application State. Hypermedia is one of the characteristics of REST that is often overlooked or missing from REST APIs. In API responses, responses that span multiple pages should provide links for users to page to the other items." @@ -188,16 +339,39 @@ header_parameters: http_method: term: HTTP method - def: "The type of action indicated in an API request, such as GET, POST, PUT, DELETE. Determines if you are reading, creating, updating, or deleting a resource." + def: "The type of action indicated in an API request, such as GET, POST, PUT, DELETE. Determines if you are reading, creating, updating, or deleting a resource. Synonymous with HTT verb and similar to HTTP operation." http_verb: term: HTTP verb - def: "The action indicated in the API request, such as GET, POST, PUT, PATCH, DELETE. Each verb refers to a different type of operation." + def: "Same as HTTP method. The term 'verb' is used because each method/verb indicates an action or behavior." +http_operation: + term: HTTP operation + def: "Refers to a combination of an HTTP method and a specific URI or endpoint. For example, a GET request to /users might retrieve a list of users, while a POST request to the same endpoint might create a new user. So, the combination of GET with /users and POST with /users indicates two distinct operations. Thus, an operation provides a more comprehensive view, as it takes into account both the action (HTTP method/verb) and the target (URI or resource)." hugo: term: Hugo def: "A static site generator that uses the Go programming language as its base. Along with Jekyll, Hugo is among the top 5 most popular static site generators. Extremely fast site generation time." +i18n: + term: i18n + def: "Short for internationalization. There are 18 letters between i and n in the word internationalization. See localization/internationalization." + +idempotent_methods: + term: Idempotent methods + def: "HTTP methods where multiple identical requests should have the same effect as a single request. For instance, GET, PUT, and DELETE are idempotent, but POST is not." + +info_openapi: + term: info (OpenAPI spec) + def: "Provides metadata about the API like title, description, version, and other details." + +interactive_api_console: + term: Interactive API console + def: "Provided by Swagger UI, this console allows users to make API calls directly from the documentation. This interactive feature enables developers to try out the API endpoints as they read through the docs." + +iteration: + term: iteration + def: "Synonymous with sprint." + java: term: Java def: "General purpose programming language commonly used in enterprise application development. Preferred by some organizations over languages like PHP." @@ -208,20 +382,48 @@ javadoc: json: term: JSON - def: "JavaScript Object Notation. A common data format for API responses, consisting of attribute-value pairs and arrays." + def: "JavaScript Object Notation. A common data format for API responses, consisting of attribute-value pairs and arrays. OpenAPI (Swagger) specifications are often written in JSON. YAML tends to be more human-readable, while JSON is often easier for machines to process." kanban: term: Kanban def: "An agile project management methodology that uses a board with columns for tracking the progress of work through different states." +l10n: + term: l10n + def: "Short for localization. There are 10 letters between the l and n in localization. See Localization/Internationalization." + +localization_internationalization: + term: Localization/Internationalization (l10n/i18n) + def: "The process of adapting documentation to different languages and regions." + +localization_testing: + term: localization testing + def: "Ensuring that the translated versions of documentation are accurate, culturally appropriate, and align with the original intent of the content." + +main_branch: + term: Main branch + def: "The primary branch where all the development is done and from where new branches are created. Previously referred to as the master branch but changed for inclusivity reasons." + markdown: term: Markdown def: "A lightweight markup language that uses plain text formatting syntax that gets converted to HTML. Popular format with developers writing documentation." +markup_language: + term: "markup language" + def: "A system for annotating content to represent its structure and presentation. Examples include Markdown and XML." + mercurial: term: Mercurial def: "A distributed revision control system, similar to Git but not as popular." +merge: + term: "merge" + def: "A Git operation that integrates changes from one branch into another. Merging takes the contents of a source branch and integrates them with a target branch. If both branches have diverged, Git will attempt to automatically combine the changes. If it cannot do this cleanly, a merge conflict occurs, which requires manual resolution by the user." + +merge_conflict: + term: "merge conflict" + def: "Occurs when two branches have changes in the same part of a file, and Git cannot automatically determine which version to use." + metadata: term: metadata def: "Data about data. In documentation, this refers to information about the document itself added to the file, like authors, dates, tags." @@ -250,6 +452,10 @@ oas: term: OAS def: "Abbreviation for OpenAPI specification." +oauth: + term: OAuth + def: "An open-standard authorization protocol that allows third-party services to exchange your information without exposing your password." + open_source: term: open source def: "Software projects with publicly available source code that can be used, modified, and distributed by anyone. Provide opportunities to contribute." @@ -268,11 +474,11 @@ openapi_initiative: openapi_specification_document: term: OpenAPI specification document - def: "The file (either in YAML or JSON syntax) that describes your REST API. Follows the OpenAPI specification format." + def: "The file (either in YAML or JSON syntax) that describes your REST API. Follows the OpenAPI specification format. See also API contract" openapi_specification: term: OpenAPI specification - def: "A vendor-neutral specification (in JSON or YAML) for describing REST APIs. Allows API providers to describe API operations, parameters, authentication methods, models, and other components in a portable document. When valid, the specification document can be used to create interactive documentation, generate client SDKs, run unit tests, and more." + def: "A vendor-neutral specification (in JSON or YAML) for describing REST APIs. Allows API providers to describe API operations, parameters, authentication methods, models, and other components in a portable document. When valid, the specification document can be used to create interactive documentation, generate client SDKs, run unit tests, and more. See also Swagger." operation: term: operation @@ -290,6 +496,10 @@ parameters: term: parameters def: "Options that can be passed with an endpoint to influence the response, such as specifying the response format or number of results returned. Common types are header, path, and query string parameters." +parameters_openapi: + term: parameters (OpenAPI spec) + def: In the OpenAPI spec, 'parameters' specifies the expected inputs for API operations, such as path, query, and header parameters. + path_parameters: term: path parameters def: "Parameters that appear within the path of the endpoint, before the query string (?). Path parameters are usually set off within curly braces {}." @@ -298,10 +508,18 @@ paths: term: paths def: "The available endpoints and operations in an API. Paths are the core resources that make up an API's interface." +paths_openapi: + term: paths (OpenAPI spec) + def: "In the OpenAPI spec, 'paths' denote the available routes or endpoints in an OpenAPI specification." + payload: term: payload def: "The data returned in the body of an API response. The payload contains the requested information or data from the API." +peer_review: + term: peer review + def: "The process where fellow technical writers or other professionals review the documentation for clarity, consistency, and accuracy." + perforce: term: Perforce def: "Revision control system often used before Git became popular. Often configured as a centralized repository instead of a distributed repository." @@ -320,7 +538,11 @@ postman: product_overview_documentation: term: product overview documentation - def: "Documentation that explains the product's purpose, audience, capabilities, and use cases. Provides high-level architectural diagrams to depict components. Transitions into getting started tutorial." + def: "Introductory content that offers a bird's-eye view of the product, its main features, and benefits. It sets the stage for users, helping them understand what the product is and why it matters." + +product_owner: + term: product owner + def: "In Scrum, the person responsible for maintaining the product backlog, setting priorities, and ensuring the team delivers maximum value to the stakeholders." publishing: term: publishing @@ -352,7 +574,7 @@ query_string_parameters: quick_reference: term: quick reference - def: "Provides a brief 1-2 page overview of core API endpoints/tasks. Lists endpoints and abbreviated descriptions. Visually groups related endpoints through tables, diagrams. Facilitates scanning system as a whole." + def: "A condensed sheet or guide that highlights the most important elements, often used for quick consultations or reminders." raml_console: term: RAML Console @@ -362,14 +584,26 @@ raml: term: RAML def: "Stands for REST API Modeling Language and is similar to OpenAPI specifications. RAML is backed by Mulesoft, a commercial API company, and uses a more YAML-based syntax in the specification." +rate_limit_headers: + term: rate limit headers + def: "Headers that inform the client about how many requests they can make in a given timeframe and when they can make additional requests after reaching the limit." + rate_limiting_and_thresholds_documentation: term: rate limiting and thresholds documentation - def: "Indicates rate limits for free and paid API tiers. Explains what happens when limits are exceeded. Notes status codes returned when limits are hit. Covers best practices to avoid hitting rate limits." + def: "Guidelines on the number of requests users can make within a specified time frame, ensuring the system remains responsive and available to all users." rate_limiting: term: rate limiting def: "Policies that restrict the number of requests a user can make to prevent overload or abuse. Requests over the limit may be throttled or blocked." +readthedocs: + term: ReadTheDocs + def: "A platform that automatically builds and deploys documentation from repositories, especially popular for open source projects." + +rebase: + term: rebase + def: "A way to integrate changes from one branch into another. It's an alternative to merging and involves reapplying changes from one line of work onto another in a sequential manner." + redoc: term: Redoc def: "An open-source tool for generating interactive API reference documentation from OpenAPI (formerly Swagger) definitions. Provides an expandable three-column layout." @@ -382,9 +616,21 @@ reference_docs: term: reference docs def: "Detailed documentation of an API's resources/endpoints, parameters, sample requests, responses, errors, etc. Provides a reference for developers." +regression_testing: + term: regression testing + def: "Testing conducted to ensure that recent changes or updates haven't negatively impacted the existing documentation or functionality." + release_notes: term: release notes - def: "Documentation describing the new features, changes, fixes, and improvements in a product release." + def: "Updates accompanying each new version of the product, detailing the additions, changes, bug fixes, and any other relevant information." + +release_planning: + term: release planning + def: "A longer-term planning meeting where the team determines which features or user stories are targeted for an upcoming release." + +remote: + term: remote + def: "A reference to an external repository, typically hosted on a server, where teams collaborate on a project. It allows developers to fetch data from or push data to the external repository. The default remote is usually named 'origin' when you clone a repository." repo: term: Repo @@ -392,15 +638,31 @@ repo: request_body: term: request body - def: "The data submitted in the body of the request, often used to create or update a resource. Defined in OpenAPI under requestBody." + def: "The data submitted in the body of the request, often used to create or update a resource. Defined in OpenAPI under requestBody. Synonymous with request payload." + +request_example: + term: request example + def: "A sample API request showcasing how the endpoint should be accessed, including any required headers, parameters, or body content." + +request_payload: + term: request payload + def: "Same as request body." request: term: request def: "A call made to an API, including the endpoint URL and parameters, headers, authorization, and other components needed to retrieve the desired information." +restructured_text: + term: reStructuredText (reST) + def: "A lightweight markup language often used with Sphinx. Offers more directive capabilities than Markdown." + resource: term: resource - def: "The core object or information managed by the API. Resources have different representations that can be retrieved or manipulated." + def: "The core object or information managed by the API. Resources have different representations that can be retrieved or manipulated. A resource can be a single entity or a collection. For example, 'users' might represent a collection of users, while users/1' represents a single user entity." + +response_body: + term: response body + def: "The data returned by the server in response to a client's request. It can contain information like resources (in case of a GET request) or status messages (like error messages). Usually in structured formats such as JSON or XML." response_code: term: response code @@ -410,6 +672,10 @@ response_example: term: response example def: "Shows a sample response from the request example. The response example is typically not comprehensive of all parameter configurations or operations, but it does correspond with the parameters passed in the request example." +response_headers: + term: response headers + def: "Information, in key-value pairs, sent in the response from the server. They can provide metadata about the response data, indicate caching rules, or specify any cookies to be stored." + response_schema: term: response schema def: "The description of the response from an API endpoint. The response schema documents the response in a more comprehensive, general way, listing each property that could possibly be returned, what each property contains, the data format of the values, the structure, optional/required aspects, and other details." @@ -418,6 +684,10 @@ response: term: response def: "The data an API returns after receiving and processing a request. The response contains requested information or confirmation that an operation succeeded." +responses_openapi: + term: responses (OpenAPI spec) + def: "In the OpenAPI spec, 'responses' describes the expected responses from API operations." + rest_api: term: REST API def: "An API that follows REST (Representational State Transfer) principles by exposing resources through endpoints that can be interacted with using standard HTTP methods like GET, POST, PUT, and DELETE. REST APIs return data in easy-to-process formats like JSON." @@ -438,18 +708,38 @@ sdk: term: SDK (Software Development Kit) def: "A collection of tools and resources that allows developers to program applications for a specific platform, software, or service. SDKs include API client libraries, documentation, code samples, and guides. Note that an SDK can include various APIs, but an API does not include an SDK." +securityschemes_openapi: + term: securitySchemes (OpenAPI spec) + def: "Defines the authentication methods used by the API, like API keys, HTTP authentication, OAuth, etc." + +servers_openapi: + term: servers (OpenAPI spec) + def: "Defines the base URLs for the API's endpoints, allowing the specification to describe APIs with varying environments like development, staging, or production." + smartbear: term: Smartbear - def: "The company that maintains and develops the Swagger tooling — Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others." + def: "The company that maintains and develops the Swagger tooling, such as Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others." + +smoke_test: + term: smoke test + def: "Preliminary testing to catch the most glaring and obvious errors in documentation, such as broken links or missing pages." + +soap: + term: SOAP (Simple Object Access Protocol) + def: A messaging protocol for communication between web services, a predecessor to REST in many contexts. specification: - term: Specification + term: specification def: "A detailed technical description of an API's architecture, endpoints, parameters, sample requests/responses, and other implementation details. The most common API specification format is OpenAPI." sphinx: term: Sphinx def: "A static site generator developed for managing documentation for Python. Sphinx is a documentation-oriented static site generator available that includes features such as search, sidebar navigation, semantic markup, and managed links. Based on Python." +sprint: + term: spring + def: "A set time period, typically 1-4 weeks, during which a specific set of tasks or work items are completed by a team. At the end of a sprint, the team aims to produce a potentially shippable product increment." + sprint_demo: term: sprint demo def: "A meeting at the end of each sprint where the Scrum team shows completed user stories/features to stakeholders and collects feedback." @@ -466,10 +756,18 @@ sprint: term: sprint def: "In Scrum, a short, timeboxed period (usually 1-4 weeks) focused on completing specific work items for a product increment." +stash: + term: stash + def: "A temporary space to store changes that you don't want to commit yet. This allows you to switch branches without committing your current changes." + stakeholder: term: stakeholder def: "People involved in some way with a product, such as engineers, product managers, executives, partners, support, and others. Stakeholders review documentation." +stakeholder_engagement: + term: stakeholder engagement + def: "The process of involving all parties that have an interest in the project, ensuring their feedback and concerns are considered." + static_site_generator: term: static site generator def: "Tool that compiles a website from simpler text-based source files like Markdown. Popular static site generators include Jekyll, Hugo, and Sphinx. A common part of docs-as-code workflows." @@ -486,10 +784,22 @@ story_points: term: story points def: "A unit of measure for expressing the overall size, complexity, and effort required to implement a user story or feature in Agile methodologies like Scrum." +subversion: + term: Subversion (SVN) + def: "Centralized version control system developed by Apache. It was one of the most popular version control systems before the rise of Git." + support: term: support def: "Resources that help API users, often provided through live chat, forums, or ticketing systems." +swagger: + term: Swagger + def: "A framework for the OpenAPI specification that includes a suite of tools for auto-generating documentation, client SDK generation, and more. In contrast to the term OpenAPI, Swagger now refers to API tooling related to the OpenAPI spec. Some of these tools include Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others. These tools are managed by Smartbear. Note: Although 'Swagger' was the original name of the OpenAPI spec, the name was later changed to OpenAPI to reinforce the open, non-proprietary nature of the standard. OpenAPI is still often referred to as Swagger." + +swagger_annotations: + term: Swagger annotations + def: "In-code annotations that developers can use within their codebase. When the application code is processed by Swagger tools, these annotations help auto-generate an OpenAPI specification." + swagger_codegen: term: Swagger Codegen def: "Generates client SDK code for a lot of different platforms (such as Java, JavaScript, Scala, Python, PHP, Ruby, Scala, and more). The client SDK code helps developers integrate your API on a specific platform and provides for more robust implementations that might include more scaling, threading, and other necessary code. In general, SDKs are toolkits for implementing the requests made with an API. Swagger Codegen generates the client SDKs in nearly every programming language." @@ -498,29 +808,45 @@ swagger_editor: term: Swagger Editor def: "An online editor that validates your OpenAPI document against the rules of the OpenAPI specification. The Swagger Editor will flag errors and give you formatting tips." +swagger_inspector: + term: Swagger Inspector + def: "An online tool for testing APIs. It helps you quickly validate and inspect API requests and responses without the need for any underlying implementation." + +swagger_petstore: + term: Swagger Petstore + def: "A basic example of an OpenAPI specification rendered by Swagger. Many people use this as a template or a reference when creating their own API specifications." + +swagger_plugins: + term: Swagger plugins + def: "Extensions or plugins available for various frameworks and platforms to integrate Swagger capabilities into the software development workflow. Examples include Maven plugins, Gradle plugins, etc." + swagger_ui: term: Swagger UI def: "An open-source web framework (on GitHub) that parses an OpenAPI specification document and generates an interactive documentation website. Swagger UI is the tool that transforms your spec into the Petstore-like site." -swagger: - term: Swagger - def: "Refers to API tooling related to the OpenAPI spec. Some of these tools include Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others. These tools are managed by Smartbear. “Swagger” was the original name of the OpenAPI spec, but the name was later changed to OpenAPI to reinforce the open, non-proprietary nature of the standard. OpenAPI is still often referred to as Swagger." - swaggerhub: term: SwaggerHub def: "A premium API platform from Smartbear that provides collaboration, mocking, testing, and publishing tools around the OpenAPI specification." -tags: - term: tags +tag: + term: tag (Git) + def: "A reference to a specific commit. Tags are typically used to capture a point in history, often used for release versions (e.g., v1.0)." + +tags_openapi: + term: tags (OpenAPI spec) def: "Groups for endpoints to organize them in the interactive documentation. Used in the OpenAPI spec." +taxonomy: + term: taxonomy + def: "The classification and organization of documentation content, often using tags, categories, or other metadata." + templating_language: term: templating language def: "Languages like Liquid, Handlebars, or Go that allow inserting dynamic content into static templates when sites are built. Help abstract complex site generation logic." terminology: term: terminology - def: "Specialized words and phrases used in a field." + def: "Specialized words and phrases used in a field. See glossary." test_case: term: test case @@ -534,9 +860,25 @@ thematic_analysis: term: thematic analysis def: "A qualitative data analysis method that involves identifying, analyzing, and reporting patterns or themes within data. Useful for synthesizing insights with AI tools." +timeboxing: + term: timeboxing + def: "Allocating a fixed amount of time for an activity. Used in Scrum for meetings and sprints to ensure they don't overrun." + +tshaped_skills: + term: T-shaped skills + def: "The concept that members of the team should have deep expertise in a specific discipline (the vertical line of the T) and broad skills and knowledge across many disciplines (the horizontal line of the T). This encourages collaboration and flexibility within teams." + tutorial: term: tutorial - def: "Guides that demonstrate how to accomplish a goal or implement a scenario using the API, often in a step-by-step format with code snippets." + def: "Detailed guides focused on teaching users how to achieve specific tasks. Broken down step-by-step, often accompanied by screenshots, code snippets, or videos." + +uri: + term: URI (Uniform Resource Identifier) + def: "A string of characters that identify a name or a resource. In RESTful APIs, URIs are used to identify resources." + +usability_testing: + term: usability testing + def: "A method to evaluate the effectiveness and clarity of documentation by observing real users as they try to achieve tasks using the documentation." user_story: term: user story @@ -546,6 +888,10 @@ user_testing: term: user testing def: "Having real users try documentation to identify problems and gaps. Essential for creating usable docs." +validation: + term: validation + def: "The process of ensuring that an OpenAPI document adheres to the OAS specification's structure and constraints." + velocity: term: velocity def: "In Scrum, the amount of work a team can successfully complete within a sprint, measured in story points. Used to forecast how much work can be done." @@ -554,10 +900,22 @@ version_control: term: version control def: "A system to track changes to code and documentation over time, support collaboration, and maintain previous versions. Examples are Git, SVN, Perforce. Also referred to as version control system." +versioning_documentation: + term: versioning (documentation) + def: "The practice of keeping multiple versions of documentation to align with different versions of the product or software. See also API versioning." + waterfall: term: waterfall def: "A sequential, linear software development methodology where phases must be completed in order before moving to the next phase." +webhooks: + term: webhooks + def: "Automated messages sent when a specific event happens on a platform. In docs-as-code, often used to trigger builds or updates when changes are pushed to a repository." + +work_in_progress: + term: Work in Progress (WIP) + def: "In Kanban, a limit set to restrict the number of items being worked on simultaneously. It ensures that teams are not overwhelmed and can maintain focus." + yaml: term: YAML def: "A human-readable data serialization format commonly used for configuration files and OpenAPI definitions. Uses indentation and whitespace for structure. Less visually noisy than JSON. Recursive acronym for YAML Ain't No Markup Language." diff --git a/_docs/glossary/glossary_groups.md b/_docs/glossary/glossary_groups.md index 0d3a8add0..9cbdd1289 100644 --- a/_docs/glossary/glossary_groups.md +++ b/_docs/glossary/glossary_groups.md @@ -9,149 +9,241 @@ section: glossary last-modified: 2023-08-31 basic_terms: - api -- rest_api -- native_library_api +- api_contract - api_documentation -- sdk -- developer_portal -- api_portal -- endpoint +- api_gateway - api_key -- curl -- request -- response -- rate_limiting +- api_portal +- api_reference +- api_versioning - authentication - authorization -- specification +- curl +- developer_portal +- endpoint +- graphql - hateos -api_reference: -- api_reference -- resource +- native_library_api +- openapi +- parameters - paths +- rate_limiting +- request +- response +- response_body +- rest_api +- resource +- sdk +- soap +- specification +- swagger +- uri api_methods: +- crud +- delete +- get - http_method +- http_operation - http_verb -- crud +- idempotent_methods - operation - post -- get - put -- delete api_parameters: -- parameters +- accept_header +- authentication_token +- authorization_tokens_or_bearers +- base_url +- bearer_token +- caching_headers +- headers - header_parameters +- oauth +- parameters - path_parameters - query_string_parameters +- rate_limit_headers - request_body +- request_example +- request_payload +- response_headers api_responses: +- content_type_header +- error_message - payload +- response_body - response_code - response_example +- response_headers - response_schema - status_code -doc_formats: -- markdown -- json -- yaml +doc_formats_and_tools: +- api_blueprint - asciidoc +- ccms +- cms +- continuous_delivery +- continuous_integration_continuous_delivery - dita +- docs_as_code +- documentation_pipeline +- documentation_theme +- frontmatter +- hat +- hugo +- i18n - java - javadoc -- templating_language +- json +- l10n +- localization_internationalization +- markdown +- markup_language +- metadata - open_source -- api_blueprint +- oxygenxml - raml -- metadata +- readthedocs +- restructured_text - schematron +- sphinx +- static_site_generator +- taxonomy +- templating_language +- versioning_documentation +- yaml version_control: -- version_control +- blame +- branch +- bitbucket +- cherry_pick +- clone +- commit +- checkout +- fork - git -- git_repo +- git_hook - github -- clone -- branch +- gitlab +- git_repo +- head +- main_branch +- merge_conflict +- mercurial +- perforce - pull - pull_request -- commit - push -- mercurial -- perforce -documentation_tools: -- docs_as_code -- static_site_generator -- continuous_delivery -- hat -- sphinx -- hugo -- oxygenxml +- rebase +- remote +- stash +- subversion +- tag +- version_control +- webhooks writing_process: +- cross_reference - outline -- review +- peer_review +- portfolio - publishing +- review - stakeholder -- cross_reference -- portfolio openapi: +- $ref_openapi +- api_console +- components_openapi +- externaldocs_openapi +- info_openapi +- mock_server - oas +- openapi_contract +- openapi_initiative - openapi_specification - openapi_specification_document -- openapi_contract - openapi_swagger -- openapi_initiative -- api_console -- mock_server -- components -- tags +- parameters_openapi +- paths_openapi +- responses_openapi +- securityschemes_openapi +- servers_openapi +- tags_openapi +- validation swagger: +- api_definition +- interactive_api_console - swagger +- swagger_annotations - swagger_codegen - swagger_editor -- swagger_ui - swaggerhub +- swagger_inspector +- swagger_petstore +- swagger_plugins +- swagger_ui project_management_concepts: -- scrum +- acceptance_criteria +- backlog +- backlog_grooming +- burndown_chart - daily_standup - definition_of_done +- epic +- iteration +- kanban +- product_owner +- release_planning +- scrum - sprint - sprint_demo - sprint_planning - sprint_retrospective +- stakeholder_engagement - story_points +- timeboxing +- tshaped_skills - user_story - velocity -- backlog -- epic -- kanban - waterfall +- work_in_progress testing_and_qa: +- accessibility_testing +- agile_testing +- assumption +- beta_testing +- bug +- feedback_loop +- localization_testing - qa +- regression_testing +- smoke_test - test_case - test_environment -- assumption +- usability_testing - user_testing -- agile_testing conceptual_docs: +- authorization_documentation +- code_sample - conceptual_docs -- product_overview_documentation +- error_message_documentation - getting_started_tutorial -- tutorial +- product_overview_documentation - quick_reference -- authorization_documentation -- reference_docs -- code_sample - rate_limiting_and_thresholds_documentation +- reference_docs - release_notes -- error_message_documentation -- terminology - support +- terminology +- tutorial api_tools_and_platforms: +- api_transformer - apiary - apigee - apimatic -- api_transformer - blobr +- customization - mulesoft +- monetization - postman - raml_console - redoc @@ -159,10 +251,9 @@ api_tools_and_platforms: - repo - smartbear - stoplight -- customization -- monetization #ai_terms: #- thematic_analysis + --- {% include coffeeshopbook.html %} @@ -174,61 +265,57 @@ api_tools_and_platforms: {% include glossary_group.html group_name="Basic terms" group_code="basic_terms" %} -## API reference terms - -{% include glossary_group.html group_name="API reference terms" group_code="api_reference" %} - ## API method terms {% include glossary_group.html group_name="API method terms" group_code="api_methods" %} ## API parameter terms -{% include glossary_group.html group_name="API parameter terms" group_code="api_parameters" %} +{% include glossary_group.html group_name="API parameter" group_code="api_parameters" %} ## API responses terms -{% include glossary_group.html group_name="API responses terms" group_code="api_responses" %} +{% include glossary_group.html group_name="API responses" group_code="api_responses" %} ## API doc format terms -{% include glossary_group.html group_name="API doc format terms" group_code="doc_formats" %} +{% include glossary_group.html group_name="API doc format" group_code="doc_formats" %} ## Version control terms -{% include glossary_group.html group_name="Version control terms" group_code="version_control" %} +{% include glossary_group.html group_name="Version control" group_code="version_control" %} ## Documentation tools terms -{% include glossary_group.html group_name="Documentation tools terms" group_code="documentation_tools" %} +{% include glossary_group.html group_name="Documentation formats and tools" group_code="doc_formats_and_tools" %} ## Writing process terms -{% include glossary_group.html group_name="Writing process terms" group_code="writing_process" %} +{% include glossary_group.html group_name="Writing process" group_code="writing_process" %} ## OpenAPI terms -{% include glossary_group.html group_name="OpenAPI terms" group_code="openapi" %} +{% include glossary_group.html group_name="OpenAPI" group_code="openapi" %} ## Swagger terms -{% include glossary_group.html group_name="Swagger terms" group_code="swagger" %} +{% include glossary_group.html group_name="Swagger" group_code="swagger" %} ## Project management terms -{% include glossary_group.html group_name="Project management terms" group_code="project_management_concepts" %} +{% include glossary_group.html group_name="Project management" group_code="project_management_concepts" %} ## Testing and QA terms -{% include glossary_group.html group_name="Testing and QA terms" group_code="testing_and_qa" %} +{% include glossary_group.html group_name="Testing and QA" group_code="testing_and_qa" %} ## Conceptual docs terms -{% include glossary_group.html group_name="Conceptual docs terms" group_code="conceptual_docs" %} +{% include glossary_group.html group_name="Conceptual docs" group_code="conceptual_docs" %} ## API tools and platform terms -{% include glossary_group.html group_name="API tools and platform terms" group_code="api_tools_and_platforms" %} +{% include glossary_group.html group_name="API tools and platform" group_code="api_tools_and_platforms" %} {% include random_ad2.html %} {% include random_ad4.html %}