diff --git a/clos.md b/clos.md
index 79faf5f3..c077b0d7 100755
--- a/clos.md
+++ b/clos.md
@@ -329,7 +329,7 @@ class (whether or not those instances exist yet).
 
 #### Slot documentation
 
-Each slot accepts one `:documentation` option. To obtain its documentation via `documentation`, you need to obtain the slot object. This can be done compatibly using an implementation such as [closer-mop](https://github.com/pcostanza/closer-mop). For instance:
+Each slot accepts one `:documentation` option. To obtain its documentation via `documentation`, you need to obtain the slot object. This can be done compatibly using a library such as [closer-mop](https://github.com/pcostanza/closer-mop). For instance:
 
 ~~~lisp
 (closer-mop:class-direct-slots (find-class 'my-class)) ; list of slots (objects)
@@ -337,6 +337,8 @@ Each slot accepts one `:documentation` option. To obtain its documentation via `
 (documentation * t) ; obtain its documentation
 ~~~
 
+Note however that generally it may be better to document slot accessors instead, as a popular viewpoint is that slots are implementation details and not part of the public interface.
+
 #### Slot type
 
 The `:type` slot option may not do the job you expect it does. If you