Update after feedback from @deshipu. Thanks

docs/design_guide.md

@@ -38,16 +38,27 @@ provide `__enter__` and `__exit__` to create a context manager usable with `with
 
 ## Verify your device
 
-Make sure device you are talking to is the device you expect. If not, raise a
+Whenever possible, make sure device you are talking to is the device you expect.
-ValueError. Beware that I2C addresses can be identical on different devices so
+If not, raise a ValueError. Beware that I2C addresses can be identical on
-read registers you know to make sure they match your expectation. Validating
+different devices so read registers you know to make sure they match your
-this upfront will help catch mistakes.
+expectation. Validating this upfront will help catch mistakes.
 
 ## Getters/Setters
 
 When designing a driver for a device, use properties for device state and use
-methods for actions that the device performs. Doing this well helps beginners
+methods for sequences of abstract actions that the device performs. State is a
-understand when to use what. It is also consistent with
+property of the device as a whole that exists regardless of what the code is
+doing. This includes things like temperature, time, sound, light and the state
+of a switch. For a more complete list see the sensor properties bullet below.
+
+Another way to separate state from actions is that state is usually something
+the user can sense themselves by sight or feel for example. Actions are
+something the user can watch. The device does this and then this.
+
+Making this separation clear to the user will help beginners understand when to
+use what.
+
+Here is more info on properties from
 [Python](https://docs.python.org/3/library/functions.html#property).
 
 ## Design for compatibility with CPython
@@ -61,6 +72,15 @@ modules to add extra functionality. By distinguishing API boundaries at modules
 you increase the likelihood that incorrect expectations are found on import and
 not randomly during runtime.
 
+### Example
+When adding extra functionality to CircuitPython to mimic what a normal
+operating system would do, either copy an existing CPython API (for example file
+writing) or create a separate module to achieve what you want. For example,
+mounting and unmount drives is not a part of CPython so it should be done in a
+module, such as a new `filesystem`, that is only available in CircuitPython.
+That way when someone moves the code to CPython they know what parts need to be
+adapted.
+
 ## Document inline
 
 Whenever possible, document your code right next to the code that implements it.
@@ -68,7 +88,11 @@ This makes it more likely to stay up to date with the implementation itself. Use
 Sphinx's automodule to format these all nicely in ReadTheDocs. The cookiecutter
 helps set these up.
 
-Use [rST](http://docutils.sourceforge.net/docs/user/rst/quickref.html) for markup.
+Use [Sphinx flavor rST](http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html) for markup.
+
+Lots of documentation is a good thing but it can take a lot of space. To
+minimize the space used on disk and on load, distribute the library as both .py
+and .mpy, MicroPython and CircuitPython's bytecode format that omits comments.
 
 ### Module description
 
@@ -148,6 +172,9 @@ object with methods that read or write into the buffer instead of creating new
 objects. `nativeio` classes are design to read and write to subsections of
 buffers.
 
+Its ok to allocate an object to return to the user. Just beware of causing more
+than one allocation per call due to internal logic.
+
 **However**, this is a memory tradeoff so do not do it for large or rarely used
 buffers.