📚 Minor doc changes

Author: danieldelcore

website/docs/ecosystem.mdx

@@ -14,9 +14,20 @@ The ecosystem is full of amazing resources and examples, please check them out.
 ## Tools
 
 - [jscodeshift](https://github.com/facebook/jscodeshift)
-- [astexplorer.net/](https://astexplorer.net/)
+- [astexplorer.net](https://astexplorer.net/)
 - [recast](https://github.com/benjamn/recast)
 
+## Blogs & Guides
+
+- [Writing your very first codemod with jscodeshift](https://medium.com/@andrew_levine/writing-your-very-first-codemod-with-jscodeshift-7a24c4ede31b)
+- [Automatic refactoring with codemods](https://itnext.io/automatic-refactoring-with-jscodeshift-codemods-45c219eaf992)
+- [Getting Started with Codemods](https://www.sitepoint.com/getting-started-with-codemods/)
+- [Codemods: Effective, Automated Refactoring](https://www.sitepen.com/blog/codemods-effective-automated-refactoring)
+- [Creating a custom transform for jscodeshift](https://skovy.dev/jscodeshift-custom-transform/)
+- [Building AST nodes from source code](https://dev.to/rajasegar/building-ast-nodes-from-source-code-3p49)
+- [How to write a codemod](https://vramana.github.io/blog/2015/12/21/codemod-tutorial/)
+- [Writing Javascript Codemods and Understanding AST Easily](https://katilius.dev/writing-js-codemods/)
+
 ## People
 
 Original authors of [jscodeshift](https://github.com/facebook/jscodeshift)
@@ -42,16 +53,6 @@ Creator of [recast](https://github.com/benjamn/recast)
 - [date-fns](https://github.com/date-fns/date-fns-upgrade-codemod)
 - [react-hook-form](https://github.com/react-hook-form/codemod)
 
-## Blogs & Guides
-
-- [Writing your very first codemod with jscodeshift](https://medium.com/@andrew_levine/writing-your-very-first-codemod-with-jscodeshift-7a24c4ede31b)
-- [Automatic refactoring with codemods](https://itnext.io/automatic-refactoring-with-jscodeshift-codemods-45c219eaf992)
-- [Getting Started with Codemods](https://www.sitepoint.com/getting-started-with-codemods/)
-- [Codemods: Effective, Automated Refactoring](https://www.sitepen.com/blog/codemods-effective-automated-refactoring)
-- [Creating a custom transform for jscodeshift](https://skovy.dev/jscodeshift-custom-transform/)
-- [Building AST nodes from source code](https://dev.to/rajasegar/building-ast-nodes-from-source-code-3p49)
-- [How to write a codemod](https://vramana.github.io/blog/2015/12/21/codemod-tutorial/)
-
 ## Misc
 
 - [facebook-codemod](https://github.com/facebook/codemod)

website/docs/glossary.mdx

@@ -10,6 +10,18 @@ slug: /glossary
 
 – [Reference](https://medium.com/@andrew_levine/writing-your-very-first-codemod-with-jscodeshift-7a24c4ede31b)
 
+## Transform
+
+A transform is simply a javascript function which serves as the entry-point for your codemod.
+
+For example:
+
+```jsx
+export default function transform(file, { jscodeshift: j }, options) {
+  //... codemod goes here
+}
+```
+
 ## Motion
 
 A motion (aka migration) is what we call specific actions performed within a codemod. Put simply, javascript functions that are responsible for a single action within a codemod.
@@ -26,6 +38,10 @@ For more information see: [Authoring](/docs/authoring#motions)
 
 [jscodeshift](https://github.com/facebook/jscodeshift) is the underlying library used by CodeshiftCommunity.
 
+- Provides both a CLI for running transforms and a jQuery-like API for manipulating ASTs
+- AST transformations are performed using a wrapper around [recast](https://github.com/benjamn/recast).
+- The AST is implemented in [ast-types](https://github.com/benjamn/ast-types), which is itself based on [esprima](https://esprima.org/)
+
 ## recast
 
 [recast](https://github.com/benjamn/recast) is the underlying library used by jscodeshift to parse, transform and output files as ASTs. It's a comparable library to [babel](https://babeljs.io/)
@@ -36,6 +52,8 @@ For more information see: [Authoring](/docs/authoring#motions)
 
 ## ast-types
 
+[ast-types](https://github.com/benjamn/ast-types)
+
 > Another great library authored by Ben Newman. It exposes 2 kinds of helpers that you’ll be using: functions that allow you to verify assumptions about nodes, and functions that allow you to compose new nodes to be added to an existing AST.
 
 – [Reference](https://medium.com/@andrew_levine/writing-your-very-first-codemod-with-jscodeshift-7a24c4ede31b)

website/docs/guides/when-not-to-codemod.mdx

@@ -89,7 +89,7 @@ const App = props => {
 
 ## What to do when a codemod isn't possible?
 
-### Prompting for user input
+### Prompt for user input
 
 In most cases, we recommend that you aim to do as much of the work as possible, right up until you can't reasonably to anymore. Then prompt users for their intervention.
 

website/docs/guiding-principles.mdx

@@ -8,15 +8,25 @@ There are several guiding principles we follow in this project.
 
 ## Codemods should target a version of package
 
-Code is always on the move and codemods written against a specific API, at a specific point of time aren't guaranteed to work in the future.
-We believe codemods should only aim to migrate from one API to another, by limiting the scope of change to a specific package and version.
-In doing so the scope and intent of a codemod is encoded and always obvious to users.
+Code is always on the move and codemods written against a specific API, at a specific point of time aren't guaranteed to work into the future.
+That's why we should aim to limit the scope of a codemod to migrate a specific package from one API to another.
+
+In doing so:
+
+- The scope and intent of a codemod is encoded and always obvious to users.
+- Changes to the package that occur thereafter should not affect or break older codemods.
+- Allow us to go back and patch older codemods if necessary.
+
+Conversely, if codemods were named arbitrarily, there will be no apparent sequence for the consumer to follow.
 
 ## Codemods should be playable in sequence
 
-By writing codemods that target a package and version, it should then be possible to move consumers across major versions by playing them in a sequence.
+By writing codemods that target a package and version, it should then be theoretically possible to move your consumers across multiple major versions by playing them in a sequence.
 For example, migrating from an older version of `@mylib/button` to the latest is possible by playing all available codemods in order `v14 -> v15 -> v16`.
 
+Ultimately, this is the happy-path this project strives for. But it's also important to meantion that in reality this might not always be possible depending on how your package might be consumed and how hard it might be to write a codemods for it.
+In these cases we recommend that you are aware of [when not to codemod](/docs/when-not-to-codemod) and [what to do when a codemod isn't possible](/docs/when-not-to-codemod#what-to-do-when-a-codemod-isnt-possible)
+
 ## Codemods should do as much as can be safely done, automatically and prompt for human intervention when needed
 
 Writing a codemod to completely migrate a package from one working state to another is not always feasible. Some edgecases might simply be too hard to support.