diff --git a/vscode.proposed.d.ts b/vscode.proposed.d.ts
index 5392658ada..561c4fb08f 100644
--- a/vscode.proposed.d.ts
+++ b/vscode.proposed.d.ts
@@ -474,6 +474,10 @@ declare module 'vscode' {
 	}
 
 	export interface NotebookContentProvider {
+		/**
+		 * Content providers should always use [file system providers](#FileSystemProvider) to
+		 * resolve the raw content for `uri` as the resouce is not necessarily a file on disk.
+		 */
 		openNotebook(uri: Uri, openContext: NotebookDocumentOpenContext): NotebookData | Promise<NotebookData>;
 		resolveNotebook(document: NotebookDocument, webview: NotebookCommunication): Promise<void>;
 		saveNotebook(document: NotebookDocument, cancellation: CancellationToken): Promise<void>;