[Excel] (Custom functions) Update low engagement articles #5364
Conversation
|
Learn Build status updates of commit c45976c: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
alison-mk
changed the title
|
Learn Build status updates of commit f8cfe04: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 4dd1c92: ✅ Validation status: passed
For more details, please refer to the build report. |
There was a problem hiding this comment.
Pull Request Overview
This PR updates low-engagement Excel custom functions articles to improve clarity and engagement using GitHub Copilot suggestions that were reviewed and revised by humans. The updates focus on making content more concise, actionable, and easier to understand.
Key changes:
- Streamlined language and improved readability across multiple articles
- Added practical tables, examples, and quick reference sections
- Enhanced error handling guidance with specific examples
Reviewed Changes
Copilot reviewed 6 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
docs/excel/custom-functions-runtime.md |
Added comparison section and simplified introductory text |
docs/excel/custom-functions-naming.md |
Major rewrite with tables, examples, and clearer naming guidelines |
docs/excel/custom-functions-errors.md |
Improved error handling guidance with more specific examples |
docs/excel/custom-functions-debugging.md |
Streamlined debugging instructions and clarified process |
docs/excel/custom-functions-batching.md |
Added key points section and guidance on when to avoid batching |
.markdownlint.json |
Added configuration to disable common linting issues for documentation |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 55db14c: ✅ Validation status: passed
For more details, please refer to the build report. |
| For example, if someone used your custom function in 100 cells in a spreadsheet, and then recalculated the spreadsheet, your custom function would run 100 times and make 100 network calls. By using a batching pattern, the calls can be combined to make all 100 calculations in a single network call. | ||
| ## Key points | ||
|
|
||
| - Several calls can be combined into one request that runs every short interval (for example, about 100 ms). |
There was a problem hiding this comment.
I can't figure out how to fix this sentence, but it's really ambiguous and what needs to be explained is:
- multiple calls to your customer function (during a recalc)
- resulting in multiple calls over the network.
- Which can be combined into one call over the network.
- The batching mechanism is like sending trains every 100ms. You put them on the train.
|
|
||
| - Several calls can be combined into one request that runs every short interval (for example, about 100 ms). | ||
| - Each function call gets a `Promise` that is resolved when the single combined response returns. | ||
| - Shorter intervals show results sooner but send more requests. Slightly longer intervals reduce traffic. |
There was a problem hiding this comment.
This is cart before the horse. Need to explain how it works before we talk about optimization or pros and cons.
| - Set a reasonable maximum number of items per batch (for example, 500) to keep the request size safe. | ||
| - Cache recent results if many calls use the same inputs. | ||
|
|
||
| Example scenario: 100 cells call the custom function. Instead of 100 network requests, you send one request that lists all 100 operations and then return 100 answers. |
There was a problem hiding this comment.
I like this sentence the most!
| Use batching to group calls to a remote service into one network request. This cuts down the number of trips to your remote service and helps the worksheet finish recalculating faster. | ||
|
|
||
| For example, if someone used your custom function in 100 cells in a spreadsheet, and then recalculated the spreadsheet, your custom function would run 100 times and make 100 network calls. By using a batching pattern, the calls can be combined to make all 100 calculations in a single network call. | ||
| ## Key points |
There was a problem hiding this comment.
After reading through all these bullet points, it really feels clunky. Like if this is a summary at the end, perhaps that makes more sense. I feel like the original text (will paste below) is better and maybe just move it sooner if the goal is to provide an executive summary.
To set up batching for your custom functions you'll need to write three main sections of code.
A push operation to add a new operation to the batch of calls each time Excel calls your custom function.
A function to make the remote request when the batch is ready.
Server code to respond to the batch request, calculate all of the operation results, and return the values.
There was a problem hiding this comment.
Thanks for the great feedback! I rewrote this section and reorganized the first few paragraphs of the article to incorporate your suggestions. Does this seem more accurate?
| ## Use the command line tools to debug | ||
|
|
||
| If you aren't using VS Code, you can use the command line (such as bash, or PowerShell) to run your add-in. You'll need to use the browser developer tools to debug your code in Excel on the web. You cannot debug the desktop version of Excel using the command line. | ||
| If you aren't using VS Code, you can use the command line such as bash or PowerShell to run your add-in. Use the browser developer tools to debug your code in Excel on the web. You cannot debug the desktop version of Excel from the command line. |
There was a problem hiding this comment.
I'm not sure the original statement that you "can't debug desktop Excel from the command line" is true. You can debug by right-clicking in the task pane and choosing debug to open the developer tools.
There was a problem hiding this comment.
Do you think it would be sufficient to simply remove the sentence?
| If you aren't using VS Code, you can use the command line such as bash or PowerShell to run your add-in. Use the browser developer tools to debug your code in Excel on the web. You cannot debug the desktop version of Excel from the command line. | |
| If you aren't using VS Code, you can use the command line such as bash or PowerShell to run your add-in. Use the browser developer tools to debug your code in Excel on the web. |
| 1. In developer tools, open your source code script file (**functions.js** or **functions.ts**). Your custom functions code may be located near the end of the file. | ||
| 1. In the custom function source code, apply a breakpoint by selecting a line of code. | ||
|
|
||
| If you need to change the code, you can make edits in VS Code and save the changes. Refresh the browser to see the changes loaded. |
There was a problem hiding this comment.
This is the same sentence as earlier but copilot didn't change it. Interesting.
Co-authored-by: David Chesnut <[email protected]>
|
Learn Build status updates of commit 2b391ef: ❌ Validation status: errorsPlease follow instructions here which may help to resolve issue.
For more details, please refer to the build report. Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them. |
|
Learn Build status updates of commit 5f091fe: ❌ Validation status: errorsPlease follow instructions here which may help to resolve issue.
For more details, please refer to the build report. Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 853d2bb: ✅ Validation status: passed
For more details, please refer to the build report. |
2 participants
This PR updates Custom Functions articles flagged for low engagement, using suggestions from GitHub Copilot that have then been reviewed and revised by a human. It also adds a markdownlint.json file to stop the markdown linter from flagging common and intentional design patterns in our articles (such as the first H1).
Note: The changes to Excel files in this PR are trivial. Excel articles are updated in a different PR.
Related PRs:
#5378
#5374