[PowerPoint] [Word] (Overview) Refresh (#5198)

* [PowerPoint] [Word] (Overview) Refresh

* Update docs/word/word-add-ins-core-concepts.md

Co-authored-by: Alex Jerabek <[email protected]>

---------

Co-authored-by: Alex Jerabek <[email protected]>

Author: ElizabethSamuel-MSFT

docs/develop/office-javascript-api-object-model.md

@@ -125,7 +125,7 @@ The [CustomXmlParts](/javascript/api/office/office.customxmlparts) and [CustomXm
 
  **Applies to:** Task pane add-ins for Word and PowerPoint
 
-The [Document.getFileAsync](/javascript/api/office/office.document#office-office-document-getfileasync-member(1)) method and members of the [File](/javascript/api/office/office.file) and [Slice](/javascript/api/office/office.slice) objects to provide functionality for getting entire Word and PowerPoint document files in slices (chunks) of up to 4 MB at a time. For more information, see [Get the whole document from an add-in for PowerPoint or Word](../word/get-the-whole-document-from-an-add-in-for-word.md).
+The [Document.getFileAsync](/javascript/api/office/office.document#office-office-document-getfileasync-member(1)) method and members of the [File](/javascript/api/office/office.file) and [Slice](/javascript/api/office/office.slice) objects to provide functionality for getting entire Word and PowerPoint document files in slices (chunks) of up to 4 MB at a time. For more information, see [Get the whole document from an add-in for PowerPoint or Word](../develop/get-the-whole-document-from-an-add-in-for-powerpoint-or-word.md).
 
 ## Mailbox object
 

docs/develop/support-for-task-pane-and-content-add-ins.md

@@ -90,7 +90,7 @@ If your task pane add-in runs in PowerPoint or Word, you can use the [Document.g
 
 When you call `Document.getFileAsync` you get a copy of the document in a [File](/javascript/api/office/office.file) object. The `File` object provides access to the document in "chunks" represented as [Slice](/javascript/api/office/office.slice) objects. When you call `getFileAsync`, you can specify the file type (text or compressed Open Office XML format), and size of the slices (up to 4MB). To access the contents of the `File` object, you then call `File.getSliceAsync` which returns the raw data in the [Slice.data](/javascript/api/office/office.slice#office-office-slice-data-member) property. If you specified compressed format, you will get the file data as a byte array. If you are transmitting the file to a web service, you can transform the compressed raw data to a Base64-encoded string before submission. Finally, when you are finished getting slices of the file, use the `File.closeAsync` method to close the document.
 
-For more details, see how to [get the whole document from an add-in for PowerPoint or Word](../word/get-the-whole-document-from-an-add-in-for-word.md).
+For more details, see how to [get the whole document from an add-in for PowerPoint or Word](../develop/get-the-whole-document-from-an-add-in-for-powerpoint-or-word.md).
 
 ## Read and write custom XML parts of a Word document
 

docs/reference/overview/powerpoint-add-ins-reference-overview.md

@@ -1,7 +1,7 @@
 ---
 title: JavaScript API for PowerPoint
 description: Overview of the PowerPoint JavaScript API.
-ms.date: 07/05/2019
+ms.date: 05/29/2025
 ms.service: powerpoint
 ms.localizationpriority: high
 ---
@@ -10,20 +10,20 @@ ms.localizationpriority: high
 
 A PowerPoint add-in interacts with objects in PowerPoint by using the Office JavaScript API, which includes two JavaScript object models:
 
-* **PowerPoint JavaScript API**: The [PowerPoint JavaScript API](/javascript/api/powerpoint) provides strongly-typed objects that you can use to access objects in PowerPoint.
+- **PowerPoint JavaScript API**: The [PowerPoint JavaScript API](/javascript/api/powerpoint) provides strongly-typed objects that you can use to access objects in PowerPoint. To learn about the asynchronous nature of the PowerPoint JavaScript APIs and how they work with the presentation, see [Using the application-specific API model](../../develop/application-specific-api-model.md).
 
-* **Common APIs**: Introduced with Office 2013, the [Common API](/javascript/api/office) can be used to access features such as UI, dialogs, and client settings that are common across multiple types of Office applications.
+- **Common APIs**: The [Common API](/javascript/api/office) can be used to access features such as UI, dialogs, and client settings that are common across multiple Office applications. To learn more about using the Common API, see [Common JavaScript API object model](../../develop/office-javascript-api-object-model.md).
 
 ## Learn programming concepts
 
 See [PowerPoint add-ins overview](../../powerpoint/powerpoint-add-ins.md) for information about important programming concepts.
 
 ## Learn about API capabilities
 
-For hands-on experience using the Common API to interact with content in PowerPoint, complete the [PowerPoint add-in tutorial](../../tutorials/powerpoint-tutorial-yo.md).
-
 For detailed information about the PowerPoint JavaScript API object model, see the [PowerPoint JavaScript API reference documentation](/javascript/api/powerpoint).
 
+For hands-on experience interacting with content in PowerPoint, complete the [PowerPoint add-in tutorial](../../tutorials/powerpoint-tutorial-yo.md).
+
 ## Try out code samples in Script Lab
 
 Use [Script Lab](../../overview/explore-with-script-lab.md) to get started quickly with a collection of built-in samples that show how to complete tasks with the API. You can run the samples in Script Lab to instantly see the result in the task pane or document, examine the samples to learn how the API works, and even use samples to prototype your own add-in.

docs/reference/overview/word-add-ins-reference-overview.md

@@ -1,7 +1,7 @@
 ---
 title: Word JavaScript API overview
 description: Overview of the Word JavaScript API.
-ms.date: 02/24/2023
+ms.date: 05/29/2025
 ms.topic: concept-article
 ms.service: word
 ms.localizationpriority: high
@@ -13,7 +13,7 @@ A Word add-in interacts with objects in Word by using the Office JavaScript API,
 
 * **Word JavaScript API**: These are the [application-specific APIs](../../develop/application-specific-api-model.md) for Word. Introduced with Office 2016, the [Word JavaScript API](/javascript/api/word) provides strongly-typed objects that you can use to access objects and metadata in a Word document.
 
-* **Common APIs**: Introduced with Office 2013, the [Common API](/javascript/api/office) can be used to access features such as UI, dialogs, and client settings that are common across multiple types of Office applications.
+* **Common APIs**: The [Common API](/javascript/api/office), introduced with Office 2013, can be used to access features such as UI, dialogs, and client settings that are common across multiple Office applications.
 
 This section of the documentation focuses on the Word JavaScript API, which you'll use to develop the majority of functionality in add-ins that target Word on the web, or Word 2016 and later. For information about the Common API, see [Common JavaScript API object model](../../develop/office-javascript-api-object-model.md).
 
@@ -23,7 +23,7 @@ See [Word JavaScript object model in Office Add-ins](../../word/word-add-ins-cor
 
 ## Learn about API capabilities
 
-Use other articles in this section of the documentation to learn how to [get the whole document from an add-in](../../word/get-the-whole-document-from-an-add-in-for-word.md), [use search options in your Word add-in to find text](../../word/search-option-guidance.md), and more. See the table of contents for the complete list of available articles.
+Use other articles in this section of the documentation to learn how to [get the whole document from an add-in](../../develop/get-the-whole-document-from-an-add-in-for-powerpoint-or-word.md), [use search options in your Word add-in to find text](../../word/search-option-guidance.md), and more. See the table of contents for the complete list of available articles.
 
 For hands-on experience using the Word JavaScript API to access objects in Word, complete the [Word add-in tutorial](../../tutorials/word-tutorial.md).
 

docs/word/word-add-ins-core-concepts.md

@@ -1,7 +1,7 @@
 ---
 title: Word JavaScript object model in Office Add-ins
 description: Learn about the key components in the Word-specific JavaScript object model.
-ms.date: 02/24/2023
+ms.date: 05/29/2025
 ms.topic: concept-article
 ms.localizationpriority: high
 ---
@@ -10,33 +10,34 @@ ms.localizationpriority: high
 
 This article describes concepts that are fundamental to using the [Word JavaScript API](../reference/overview/word-add-ins-reference-overview.md) to build add-ins.
 
-> [!IMPORTANT]
-> See [Using the application-specific API model](../develop/application-specific-api-model.md) to learn about the asynchronous nature of the Word APIs and how they work with the document.
-
 ## Office.js APIs for Word
 
 A Word add-in interacts with objects in Word by using the Office JavaScript API. This includes two JavaScript object models:
 
-* **Word JavaScript API**: The [Word JavaScript API](/javascript/api/word) provides strongly-typed objects that work with the document, ranges, tables, lists, formatting, and more.
+* **Word JavaScript API**: The [Word JavaScript API](/javascript/api/word) provides strongly-typed objects that work with the document, ranges, tables, lists, formatting, and more. To learn about the asynchronous nature of the Word APIs and how they work with the document, see [Using the application-specific API model](../develop/application-specific-api-model.md).
 
-* **Common APIs**: The [Common API](/javascript/api/office) give access to features such as UI, dialogs, and client settings that are common across multiple Office applications.
+* **Common APIs**: The [Common API](/javascript/api/office) give access to features such as UI, dialogs, and client settings that are common across multiple Office applications. To learn more about using the Common API, see [Common JavaScript API object model](../develop/office-javascript-api-object-model.md).
 
 While you'll likely use the Word JavaScript API to develop the majority of functionality in add-ins that target Word, you'll also use objects in the Common API. For example:
 
 * [Office.Context](/javascript/api/office/office.context): The `Context` object represents the runtime environment of the add-in and provides access to key objects of the API. It consists of document configuration details such as `contentLanguage` and `officeTheme` and also provides information about the add-in's runtime environment such as `host` and `platform`. Additionally, it provides the `requirements.isSetSupported()` method, which you can use to check whether a specified requirement set is supported by the Word application where the add-in is running.
 * [Office.Document](/javascript/api/office/office.document): The `Office.Document` object provides the `getFileAsync()` method, which you can use to download the Word file where the add-in is running. This is separate from the [Word.Document](/javascript/api/word/word.document) object.
 
-![Differences between the Word JS API and Common APIs.](../images/word-js-api-common-api.png)
+:::image type="content" source="../images/word-js-api-common-api.png" alt-text="Differences between the Word JS API and Common APIs.":::
 
 ## Word-specific object model
 
-To understand the Word APIs, you must understand how the components of a document are related to one another.
+To understand the Word APIs, you must understand how key components of a document are related to one another.
+
+* The document contains sections, pages, and document-level entities such as settings and custom XML parts.
+* A section contains a body.
+* A body has paragraphs, content controls, and range objects, among others.
+* A range is a contiguous area of content, including text, whitespace, tables, and images. The [Word.Range](/javascript/api/word/word.range) object contains most of the text manipulation methods.
+* A list contains numbered or bulleted paragraphs.
+* The document is contained in a window.
+* A window has panes. A pane surrounds the visible area of the document.
 
-* The **Document** contains the **Section**s, and document-level entities such as settings and custom XML parts.
-* A **Section** contains a **Body**.
-* A **Body** gives access to **Paragraph**s, **ContentControl**s, and **Range** objects, among others.
-* A **Range** represents a contiguous area of content, including text, white space, **Table**s, and images. It also contains most of the text manipulation methods.
-* A **List** represents text in a numbered or bulleted list.
+For the full set of objects supported by the Word JavaScript API, see [Word JavaScript API](/javascript/api/word).
 
 ## See also
 

docs/word/word-add-ins-programming-overview.md

@@ -1,7 +1,7 @@
 ---
 title: Word add-ins overview
 description: Learn the basics of Word add-ins.
-ms.date: 05/16/2024
+ms.date: 05/29/2025
 ms.topic: overview
 ms.custom: scenarios:getting-started
 ms.localizationpriority: high
@@ -17,28 +17,28 @@ Word add-ins are one of the many development options that you have on the [Offic
 
 The following figure shows an example of a Word add-in that runs in a task pane.
 
-![Add-in running in a task pane in Word.](../images/word-add-in-show-host-client.png)
+:::image type="content" source="../images/word-add-in-show-host-client.png" alt-text="Add-in running in a task pane in Word.":::
 
 The Word add-in can do the following:
 
   1. Send requests to the Word document.
   1. Use JavaScript to access the paragraph object and update, delete, or move the paragraph.
 
-For example, the following code shows how to append a new sentence to the first selected paragraph.
+For example, the following code shows how to append a new sentence to the first paragraph.
 
 ```js
 await Word.run(async (context) => {
-  const paragraphs = context.document.getSelection().paragraphs;
+  const paragraphs = context.document.body.paragraphs;
   paragraphs.load();
   await context.sync();
+
   paragraphs.items[0].insertText(' New sentence in the paragraph.',
                                    Word.InsertLocation.end);
   await context.sync();
 });
-
 ```
 
-You can use any web server technology to host your Word add-in, such as ASP.NET, NodeJS, or Python. Use your favorite client-side framework—Ember, Backbone, Angular, React—or stick with plain JavaScript to develop your solution. You can also use services like Azure to [authenticate](../develop/overview-authn-authz.md) and host your application.
+You can use any web server technology to host your Word add-in, such as ASP.NET, NodeJS, or Python. Use your favorite client-side framework—Ember, Backbone, Angular, React—or stick with plain JavaScript to develop your solution. You can also use services like Microsoft Entra and Microsoft Azure to [authenticate](../develop/overview-authn-authz.md) and host your application respectively.
 
 The Word JavaScript APIs give your application access to the objects and metadata found in a Word document. You can use these APIs to create add-ins that target the following clients.
 
@@ -51,11 +51,13 @@ Write your add-in once, and it will run in all supported versions of Word across
 
 ## JavaScript APIs for Word
 
-You can use two sets of JavaScript APIs to interact with the objects and metadata in a Word document. The first is the [Common API](/javascript/api/office), which was introduced in Office 2013. Many of the objects in the Common API can be used in add-ins hosted by two or more Office clients. This API uses callbacks extensively.
+You can use two sets of JavaScript APIs to interact with the objects and metadata in a Word document.
+
+The first is the [Word JavaScript API](/javascript/api/word). This is an [application-specific API model](../develop/application-specific-api-model.md) that was introduced with Word 2016. It's a strongly-typed object model that you can use to create Word add-ins that target Word 2016 and later on Windows and on Mac. This object model uses promises and provides access to Word-specific objects like [body](/javascript/api/word/word.body), [content controls](/javascript/api/word/word.contentcontrol), [inline pictures](/javascript/api/word/word.inlinepicture), and [paragraphs](/javascript/api/word/word.paragraph). The Word JavaScript API includes TypeScript definitions and vsdoc files so that you can get code hints in your IDE.
 
-The second is the [Word JavaScript API](/javascript/api/word). This is an [application-specific API model](../develop/application-specific-api-model.md) that was introduced with Word 2016. It's a strongly-typed object model that you can use to create Word add-ins that target Word 2016 and later on Windows and on Mac. This object model uses promises and provides access to Word-specific objects like [body](/javascript/api/word/word.body), [content controls](/javascript/api/word/word.contentcontrol), [inline pictures](/javascript/api/word/word.inlinepicture), and [paragraphs](/javascript/api/word/word.paragraph). The Word JavaScript API includes TypeScript definitions and vsdoc files so that you can get code hints in your IDE.
+The second is the [Common API](/javascript/api/office), which was introduced in Office 2013. Many of the objects in the Common API can be used in add-ins hosted by two or more Office clients. This API uses callbacks extensively.
 
-Currently, all Word clients support the shared Office JavaScript API, and most clients support the Word JavaScript API. For details about supported clients, see [Office client application and platform availability for Office Add-ins](/javascript/api/requirement-sets).
+Currently, all Word clients support Word JavaScript API and the shared Office JavaScript API. For details about supported clients, see [Office client application and platform availability for Office Add-ins](/javascript/api/requirement-sets).
 
 We recommend that you start with the Word JavaScript API because the object model is easier to use. Use the Word JavaScript API if you need to access the objects in a Word document.