diff --git a/README.md b/README.md
index d38ab78..c146dc2 100644
--- a/README.md
+++ b/README.md
@@ -112,7 +112,6 @@
     name = "my_code",
     srcs = glob(["*.ts"]),
     deps = ["//path/to/other:library"],
-    tsconfig = "//:tsconfig.json",
 )
 ```
 
@@ -123,10 +122,17 @@
 The resulting `.d.ts` file paths will be printed. Additionally, the `.js`
 outputs from TypeScript will be written to disk, next to the `.d.ts` files <sup>1</sup>.
 
+Note that the `tsconfig.json` file used for compilation should be the same one
+your editor references, to keep consistent settings for the TypeScript compiler.
+By default, `ts_library` uses the `tsconfig.json` file in the workspace root
+directory. See the notes about the `tsconfig` attribute in the [ts_library API docs].
+
 > <sup>1</sup> The
 > [declarationDir](https://www.typescriptlang.org/docs/handbook/compiler-options.html)
 > compiler option will be silently overwritten if present.
 
+[ts_library API docs]: http://tsetse.info/api/build_defs.html#ts_library
+
 ### Serving TypeScript for development
 
 There are two choices for development mode:
diff --git a/internal/build_defs.bzl b/internal/build_defs.bzl
index db78616..8d867d3 100644
--- a/internal/build_defs.bzl
+++ b/internal/build_defs.bzl
@@ -162,7 +162,7 @@
     )
     return ts_providers_dict_to_struct(ts_providers)
 
-_ts_library = rule(
+ts_library = rule(
     _ts_library_impl,
     attrs = dict(COMMON_ATTRIBUTES, **{
         "srcs": attr.label_list(
@@ -177,7 +177,16 @@
         "tsconfig": attr.label(
             doc = """A tsconfig.json file containing settings for TypeScript compilation.
             Note that some properties in the tsconfig are governed by Bazel and will be
-            overridden, such as `target` and `module`.""",
+            overridden, such as `target` and `module`.
+
+            The default value is set to `//:tsconfig.json` by a macro. This means you must
+            either:
+
+            - Have your `tsconfig.json` file in the workspace root directory
+            - Use an alias in the root BUILD.bazel file to point to the location of tsconfig:
+              `alias(name="tsconfig.json", actual="//path/to:tsconfig-something.json")`
+            - Give an explicit `tsconfig` attribute to all `ts_library` targets
+            """,
             allow_files = True,
             single_file = True,
         ),
@@ -219,7 +228,19 @@
 """
 
 def ts_library_macro(tsconfig = None, **kwargs):
+    """Wraps `ts_library` to set the default for the `tsconfig` attribute.
+
+    This must be a macro so that the string is converted to a label in the context of the
+    workspace that declares the `ts_library` target, rather than the workspace that defines
+    `ts_library`, or the workspace where the build is taking place.
+
+    This macro is re-exported as `ts_library` in the public API.
+
+    Args:
+      tsconfig: the label pointing to a tsconfig.json file
+      **kwargs: remaining args to pass to the ts_library rule
+    """
     if not tsconfig:
         tsconfig = "//:tsconfig.json"
 
-    _ts_library(tsconfig = tsconfig, **kwargs)
+    ts_library(tsconfig = tsconfig, **kwargs)