-
Notifications
You must be signed in to change notification settings - Fork 27
/
Copy pathglossary.yml
921 lines (693 loc) · 46.7 KB
/
glossary.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
$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."
api:
term: API (Application Programming Interface)
def: "A set of definitions, protocols, and tools for building software applications. APIs allow different systems to interact with each other programmatically. This course focuses mostly on REST APIs, but there are also language-based APIs such as Java, C++, Python, and more. I refer to these as native library APIs."
api_blueprint:
term: API Blueprint
def: "The API Blueprint spec is an alternative specification to OpenAPI or RAML. API Blueprint is written in a Markdown-flavored syntax. See API Blueprint in this course, or go to API Blueprint's homepage to learn more."
api_console:
term: API Console
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
def: "Documentation that describes how an API works so that developers can understand and use it. Usually includes reference documentation, tutorials, code samples, and overviews."
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."
api_reference:
term: API reference
def: "The documentation describing the endpoints, requests, parameters, responses, schemas, and other details about an API."
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."
apigee:
term: Apigee
def: "Similar to Apiary, Apigee provides services for you to manage the whole lifecycle of your API. Specifically, Apigee lets you 'manage API complexity and risk in a multi- and hybrid-cloud world by ensuring security, visibility, and performance across the entire API landscape.' Supports the OpenAPI spec. See apigee.com."
apimatic:
term: APIMATIC
def: "Supports most REST API description formats (OpenAPI, RAML, API Blueprint, etc.) and provides SDK code generation, conversions from one spec format to another, and many more services. For example, you can automatically convert Swagger 2.0 to 3.0 using the API Transformer service on this site."
asciidoc:
term: Asciidoc
def: "A lightweight text format that provides more semantic features than Markdown. Used in some static site generators, such as Asciidoctor or Nanoc."
assumption:
term: assumption
def: "An idea taken for granted without confirmation. Docs often make faulty assumptions about user knowledge."
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: "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."
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: "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_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: "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: "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
def: "A link from one documentation topic to a related topic to help users navigate and find associated information."
crud:
term: CRUD
def: "Create, Read, Update, Delete. These four programming operations are often compared to POST, GET, PUT, and DELETE with REST API operations."
curl:
term: curl
def: "A command line tool for transferring data with URL syntax. curl is commonly used to demonstrate example API requests."
customization:
term: customization
def: "Changing the default styling and branding of a platform. Blobr enables customizing the portal name, logo, colors, domain, etc."
daily_standup:
term: daily standup
def: "A short daily meeting, usually held in the morning, where each member of the Scrum team describes what they accomplished yesterday, plans for today, and any blocking issues."
definition_of_done:
term: definition of done
def: "In Scrum, the agreed upon criteria that user stories must meet before they can be considered complete and shippable."
delete:
term: DELETE
def: "An HTTP method that removes a resource."
developer_portal:
term: developer portal
def: "A website that brings together documentation, code samples, SDKs, tools, and other resources to help developers use an API or set of APIs. The portal is a central location for developers to access everything they need."
dita:
term: DITA
def: "Darwin Information Typing Architecture, an XML-based architecture for authoring, producing, and delivering technical information. Allows topic-based authoring."
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 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: "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
def: "An HTTP method that retrieves a resource. GET requests do not modify any resources."
getting_started_tutorial:
term: getting started tutorial
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
def: "In Git, a repo (short for repository) stores your project's code. Usually, you only store non-binary (human-readable) text files in a repo, because Git can run diffs on text files and show you what has changed."
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: HATEOAS
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."
header_parameters:
term: header parameters
def: "Parameters that are included in the request header, usually related to authorization."
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. Synonymous with HTT verb and similar to HTTP operation."
http_verb:
term: HTTP verb
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."
javadoc:
term: Javadoc
def: "A documentation generator that produces API reference documentation from Java source code comments formatted with tags. The Javadoc tool is the standard for documenting Java APIs."
json:
term: JSON
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."
method:
term: method
def: "An HTTP verb that indicates the desired action for an API request. Common HTTP methods are GET, POST, PUT, and DELETE."
mock_server:
term: mock server
def: "A simulated API server that returns sample responses without any actual implementation or processing of requests. Mock servers allow testing interactions with an API before it's built."
monetization:
term: monetization
def: "Generating revenue from an API, through methods like usage fees, rate limits, subscriptions, or freemium models."
mulesoft:
term: Mulesoft
def: "Similar to Apiary or Apigee, Mulesoft provides an end-to-end platform for designing, developing, and distributing your APIs."
native_library_api:
term: native library API
def: "API with code libraries for incorporating functionality directly into an application, rather than using network calls. Tied to a language and usually has a library file that you integrate into your project. Also called library API or class-based API."
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."
openapi_swagger:
term: OpenAPI (Swagger)
def: "A specification for describing REST APIs that can be used to generate interactive documentation, code libraries, and more."
openapi_contract:
term: OpenAPI contract
def: "Synonym for OpenAPI specification document."
openapi_initiative:
term: OpenAPI Initiative
def: "The governing body that directs the OpenAPI specification. Backed by the Linux Foundation."
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. 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. See also Swagger."
operation:
term: operation
def: "The type of API call, such as GET, POST, PUT, DELETE. Indicates allowed interactions with a resource."
outline:
term: outline
def: "A list of section headings and bullet points that maps out the structure and content to be covered in a document. Outlines are created before writing begins."
oxygenxml:
term: OxygenXML
def: "An XML editor and publishing platform that supports DITA and other XML formats, along with Markdown and docs-as-code workflows."
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 {}."
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."
portfolio:
term: portfolio
def: "A collection of writing samples and projects that demonstrates a technical writer's skills and experience. Useful for job applications."
post:
term: POST
def: "An HTTP method that creates a new resource."
postman:
term: Postman
def: "A GUI application for interacting with APIs by constructing requests and viewing responses. Simplifies API testing. Useful for exploring and trying out APIs."
product_overview_documentation:
term: product overview documentation
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
def: "The act of finalizing documentation and making it publicly available on a website or elsewhere. The last step of the writing process."
pull_request:
term: pull request
def: "GitHub workflow where proposed code changes in a branch are submitted for review and potential merging into the project's main branch."
pull:
term: pull
def: "In Git, when you pull from origin (the main location where you cloned the repo), you get the latest updates from origin onto your local system."
push:
term: push
def: "In Git, when you want to update the origin (the main location where you cloned the repo) with the latest updates from your local copy, you run git push. Your updates will bring origin back into sync with your local copy."
put:
term: PUT
def: "An HTTP method that updates an existing resource or creates a new resource if it doesn't exist."
qa:
term: QA
def: "Quality Assurance. Team responsible for testing products before release to ensure quality."
query_string_parameters:
term: query string parameters
def: "The part of a URL after the ? symbol that contains parameter names and values to configure an endpoint request. Multiple parameters are separated with &."
quick_reference:
term: quick reference
def: "A condensed sheet or guide that highlights the most important elements, often used for quick consultations or reminders."
raml_console:
term: RAML Console
def: "In Mulesoft, the RAML Console is where you design your RAML spec. Similar to the Swagger Editor for the OpenAPI spec."
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: "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."
redocly:
term: Redocly
def: "Company that offers premium tools and services for API documentation, including enhanced Redoc, CLI tools, and developer portals."
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: "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
def: "A tool for consolidating and managing many smaller repos with one system."
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. 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. 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
def: "HTTP status codes returned with API responses indicating success, failure, errors, etc."
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."
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."
review:
term: review
def: "The process of having stakeholders and subject matter experts read draft documentation and provide feedback to improve the content."
schematron:
term: schematron
def: "XML vocabulary that allows validating the structure and content in XML documents against a set of rules. Can help enforce standards."
scrum:
term: Scrum
def: "An agile project management framework that breaks down product development into short, iterative sprints with daily standup meetings."
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, 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
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."
sprint_planning:
term: sprint planning
def: "A meeting at the start of each sprint where the product owner and team select user stories from the backlog to work on that align with the sprint goal."
sprint_retrospective:
term: sprint retrospective
def: "A meeting at the end of each sprint where the Scrum team reflects on what went well, what needs improvement, and lessons learned from the sprint."
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."
status_code:
term: status code
def: "A 3-digit number returned with an API response indicating whether the request succeeded or failed. Common status codes include 200 (success), 400 (bad request), 404 (not found), 500 (server error)."
stoplight:
term: Stoplight
def: "Provides a platform with visual modeling tools to create an OpenAPI document for your API — without requiring you to know the OpenAPI spec details or code the spec line by line."
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."
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."
swaggerhub:
term: SwaggerHub
def: "A premium API platform from Smartbear that provides collaboration, mocking, testing, and publishing tools around the OpenAPI specification."
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. See glossary."
test_case:
term: test case
def: "A scenario to execute to validate expected behavior and responses. QA teams run test cases."
test_environment:
term: test environment
def: "The system setup used to experiment with and validate code, APIs, apps, etc. Often a separate test server."
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: "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
5731
real users as they try to achieve tasks using the documentation."
user_story:
term: user story
def: "A high-level definition of a requirement or feature from an end-user perspective, used as the basis for planning in Agile methodologies."
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."
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."