diff --git a/doc/api/fs.md b/doc/api/fs.md
index f694223ace3051..7fb7bd9061a72f 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -102,6 +102,11 @@ example `fs.readdirSync('c:\\')` can potentially return a different result than
 `fs.readdirSync('c:')`. For more information, see
 [this MSDN page][MSDN-Rel-Path].
 
+*Note:* On Windows, opening an existing hidden file using the `w` flag (either
+through `fs.open` or `fs.writeFile`) will fail with `EPERM`. Existing hidden
+files can be opened for writing with the `r+` flag. A call to `fs.ftruncate` can
+be used to reset the file contents.
+
 ## Threadpool Usage
 
 Note that all file system APIs except `fs.FSWatcher()` and those that are