Update readme

README.md

@@ -2,17 +2,23 @@
 
 # TypeScript types for Adobe Products
 
-Repository for declaration files generated by [extendscript-xml-to-typescript converter](https://github.com/aenhancers/extendscript-xml-to-typescript).
+Repository for typedef files for various Adobe Creative Cloud products.
 
 [<img src="https://i.imgur.com/VMx9MeE.jpg" width="560" height="315" />](http://youtu.be/h-c7A8pQzx8)
 
 ![gif](_resources/gif.gif)
 
 </div>
 
+---
+
 ## Prerequisites
 
-Install [Node.js](https://nodejs.org/en/download/) and [TypeScript](https://www.typescriptlang.org/#download-links) and git.
+* [Node.js](https://nodejs.org/en/download/)
+* [TypeScript](https://typescriptlang.org/#download-links)
+* [git](https://git-scm.com/)
+
+---
 
 ## Your first script for eg. Adobe Illustrator
 
@@ -37,16 +43,52 @@ tsc
 # open Adobe Illustrator -> File -> Scripts -> Other Script -> and open index.js
 ```
 
-## More typings
+---
 
-- [Adobe's offical typings](https://github.com/Adobe-CEP/Samples/tree/master/TypeScript/typings)
-- [BrightShadow/CSInterface-TS](https://github.com/BrightShadow/CSInterface-TS)
+## FAQ
+
+### Where do these typedefs come from?
+
+Everything in this project was generated through one of the following methods:
+
+1. Using this [extendscript-xml-to-typescript converter](https://github.com/aenhancers/extendscript-xml-to-typescript) tool to convert scripting dictionaries to typedef format
+   - *note that this only works for a few select apps, and has been found to generate incorrect data in some cases*
+2. By hand, through referencing Adobe's official release announcements & developer exploration through the API.
+
+### Why are there different versions of docs per version of each host app?
+
+This repo aims to maintain a history of typedefs _for each given version of each hostapp_.
+
+This way, if you're developing a tool aimed at, say, Adobe After Effects v18.0, you can have your tool specifically use _those_ typedefs, and know that you're not using features that were introduced in a later version.
+
+#### Why does this matter?
+
+**For public, commercial tools:** with some hostapps, it's generally accepted that the app's user base will be spread out among multiple versions of the software. Targeting a slightly older version ensures wider adoption than focusing solely on the latest version.
+
+**For internal, proprietary tools:** some companies mandate that all artists use a specific (older) version; having separate definitions for that version allows for this specific targeting.
+
+### Which should I use?
+
+This really depends on your needs; if you're hoping to release a commercial tool and assume that all users are using a specific version or newer, use that! If you need to leverage a feature added at a specific point, use those typedefs instead & let your users know this is the minimum supported version.
+
+### Why are some release versions missing?
+
+Two possible answers! Either
+
+1. There haven't been any API changes for that given version, or
+2. Nobody's taken the time to add typedefs for that version; feel free to [open a PR](https://github.com/aenhancers/Types-for-Adobe/pulls)!
+
+---
 
 ## Contributors
 
-Thanks to [vespakoen](https://github.com/vespakoen), [atarabi](https://github.com/atarabi), [lm913](https://github.com/lm913), [zlovatt](https://github.com/zlovatt).
+Thanks to [all of our contributors](https://github.com/aenhancers/Types-for-Adobe/graphs/contributors) for helping make this project succeed!
+
+Have something to add? Please [open a PR](https://github.com/aenhancers/Types-for-Adobe/pulls)!
 
-## Showcase
+---
 
-[Add your project](https://github.com/aenhancers/Types-for-Adobe/edit/master/README.md).
+## More typings
 
+- [Adobe's offical typings](https://github.com/Adobe-CEP/Samples/tree/master/TypeScript/typings)
+- [BrightShadow/CSInterface-TS](https://github.com/BrightShadow/CSInterface-TS)