diff --git a/packages/gatsby-source-filesystem/README.md b/packages/gatsby-source-filesystem/README.md
index 898da4eabf636..805e958f61871 100644
--- a/packages/gatsby-source-filesystem/README.md
+++ b/packages/gatsby-source-filesystem/README.md
@@ -40,25 +40,45 @@ module.exports = {
   ],
 };
 ```
-## API
 
-`gatsby-source-filesystem` reveals two APIs:
+## How to query
+
+You can query file nodes like the following:
+
+```graphql
+{
+  allFile {
+    edges {
+      node {
+        extension
+        dir
+        modifiedTime
+      }
+    }
+  }
+}
+```
+
+## Helper functions
+
+`gatsby-source-filesystem` exports two helper functions:
 - `createFilePath`
 - `createRemoteFileNode`
 
 ### createFilePath
+
+When building pages from files, you often want to create a URL from a file's path on the file system. E.g. if you have a markdown file at `src/content/2018-01-23-an-exploration-of-the-nature-of-reality/index.md`, you might want to turn that into a page on your site at `example.com/2018-01-23-an-exploration-of-the-nature-of-reality/`. `createFilePath` is a helper function to make this task easier.
+
 ```javascript
-// In your gatsby-node.js
 createFilePath({
-  // The node you'd like to create into a filepath
-  // Param from `onCreateNode` can be used here
-  // ie: a markdown file, JSON data, etc
+  // The node you'd like to convert to a path
+  // e.g. froom a markdown, JSON, YAML file, etc
   node:
   // Method used to get a node
-  // Param from `onCreateNode` can be used here
+  // The parameter from `onCreateNode` should be passed in here
   getNode:
-  // the slug structure you'd like to create
-  // Defaults to `src/pages`
+  // The base path for your files.
+  // Defaults to `src/pages`. For the example above, you'd use `src/contents`.
   basePath:
   // Whether you want your file paths to contain a trailing `/` slash
   // Defaults to true
@@ -67,15 +87,17 @@ createFilePath({
 ```
 
 #### Example usage
-The following is taken from [Gatsby Tutorial, Part Four](https://www.gatsbyjs.org/tutorial/part-four/#programmatically-creating-pages-from-data) and is used to create URL slugs from markdown pages.
+The following is taken from [Gatsby Tutorial, Part Four](https://www.gatsbyjs.org/tutorial/part-four/#programmatically-creating-pages-from-data) and is used to create URL slugs for markdown pages.
 
 ```javascript
+const { createFilePath } = require(`gatsby-source-filesystem`)
+
 exports.onCreateNode = ({ node, getNode, boundActionCreators }) => {
     const { createNodeField } = boundActionCreators
     // Ensures we are processing only markdown files
     if (node.internal.type === 'MarkdownRemark') {
         // Use `createFilePath` to turn markdown files in our `data/faqs` directory into `/faqs/slug`
-        const relativeFilePath = createFilePath({ node, getNode, basePath: 'data/faqs/', trailingSlash: false })
+        const relativeFilePath = createFilePath({ node, getNode, basePath: 'data/faqs/' })
 
         // Creates new query'able field with name of 'slug'
         createNodeField({
@@ -92,21 +114,3 @@ exports.onCreateNode = ({ node, getNode, boundActionCreators }) => {
 ```javascript
 TO DO
 ```
-
-## How to query
-
-You can query file nodes like the following:
-
-```graphql
-{
-  allFile {
-    edges {
-      node {
-        extension
-        dir
-        modifiedTime
-      }
-    }
-  }
-}
-```