Merge pull request #503 from cgewecke/truffle-library

Add truffle library documentation

src/docs/truffle/getting-started/writing-external-scripts.md

@@ -80,7 +80,6 @@ know how we can improve it!
      // config_[1] starts remaining parameters.
      if (config.help) {
        console.log(`Usage: truffle run hello [name]`);
-       done(null, [], []);	
        return;
      }
 
@@ -105,3 +104,41 @@ know how we can improve it!
     ```
     npm publish
     ```
+
+## Importing Truffle as a module
+
+```javascript
+const truffle = require("truffle");
+```
+
+Beginning with `v5.0.30`, Truffle exports the methods listed in [truffle-core/index.js](https://github.com/trufflesuite/truffle/blob/develop/packages/truffle-core/index.js). This means
+your plugin can consume the user's Truffle instance as a library and access a subset of its internal command APIs.
+
+These are useful if you need to touch several Truffle commands in succession. For example, imagine a plugin that evaluated how a contract system performed at different levels of solc optimization. Its workflow might look like:
+```
+for a range of solc settings:
+   compile contracts to a temp folder
+   run user's tests using the temp artifacts
+   measure and save gas usage data
+
+aggregate data and report
+```
+The Truffle library lets you do this without making the user add configuration or string their own commands together.
+
+:warning: **Important Note** :warning:
+
+Truffle does not guarantee its internal APIs will follow semver. You should be prepared for your user
+to run any Truffle version and handle mismatches gracefully. By using the library **you are entering into a gentleperson's agreement** to manage API volatility and other contingencies on your users' behalf. Some tips:
+
++ Always `require` Truffle in a try/catch block
++ At runtime, verify the API components you need are actually exposed
++ Consume separately published (and semver guaranteed) Truffle modules when possible
++ Add yourself to the Truffle repo watch list on GitHub and keep abreast of internal changes that
+might affect you.
++ Do not go on vacation
+
+
+
+
+
+