Add much more detail to the README

Author: parkera

Docs/Design.md

@@ -1,10 +1,4 @@
 
-# Roadmap and Design Principles
-
-## Part of Swift 3.0
-
-Our primary goal is to achieve implementation parity with Foundation on Apple platforms. This will help to enable the overall Swift 3 roadmap goal of **portability**.
-
 # Design Principles
 
 ## Portability
@@ -129,4 +123,4 @@ There are some additional considerations when working on the CoreFoundation part
 
 * Surround Swift-runtime-specific code with the standard macro `#if DEPLOYMENT_RUNTIME_SWIFT`.
 * Surround platform-specific code with our standard macros `DEPLOYMENT_TARGET_MACOSX`, `DEPLOYMENT_TARGET_EMBEDDED` (all iOS platforms and derivatives), `DEPLOYMENT_TARGET_LINUX`.
-* Follow the code style of the .c file that you are working in.
+* Follow the coding style of the .c file that you are working in.

README.md

@@ -14,6 +14,14 @@ There is more information on the Foundation framework [here](https://developer.a
 
 This project provides an implementation of the Foundation API for platforms where there is no Objective-C runtime. On OS X, iOS, and other Apple platforms, apps should use the Foundation that comes with the operating system. Our goal is to abstract away the exact underlying platform as much as possible.
 
+## Goals
+
+### Part of Swift 3.0
+
+Our primary goal is to achieve implementation parity with Foundation on Apple platforms. This will help to enable the overall Swift 3 goal of **portability**.
+
+In our first year, we are not looking to make major API changes to the library. We feel that this will hamper the primary goal. There are some areas where API changes are unavoidable, however. For more information on those APIs and the overall design of Foundation, please see [our design document](Docs/Design.md).
+
 ## Using Foundation
 
 Here is a simple `main.swift` file which uses Foundation. This guide assumes you have already installed a version of the latest [Swift binary distribution](https://swift.org/downloads#latest).
@@ -22,14 +30,47 @@ Here is a simple `main.swift` file which uses Foundation. This guide assumes you
 import Foundation
 
 // Make an URLComponents instance
-let swifty = NSURLComponents(string: "http://swift.org")!
+let swifty = NSURLComponents(string: "https://swift.org")!
 
 // Print something useful about the URL
 print("\(swifty.host!)")
 
 // Output: "swift.org"
 ```
 
+You will want to use the [Swift Package Manager](https://swift.org/package-manager/) to build your Swift apps.
+
 ## Working on Foundation
 
 Please see [Getting Started](Docs/GettingStarted.md).
+
+## FAQ
+
+##### Why include Foundation on Linux?
+
+We believe that the Swift standard library should remain small and laser-focused on providing support for language primitives. The Foundation framework has the flexibility to include higher-level concepts and to build on top of the standard library, much in the same way that it builds upon the C standard library and Objective-C runtime on Darwin platforms.
+
+##### Why include NSString, NSDictionary, NSArray, and NSSet? Aren't those already provided by the standard library?
+
+There are several reasons why these types are useful in Swift as distinct types from the ones in the standard library:
+
+* They provide reference semantics instead of value semantics, which is a useful tool to have in the toolbox.
+* They can be subclassed to specialize behavior while maintaining the same interface for the client.
+* They exist in archives, and we wish to maintain as much forward and backward compatibility with persistence formats as is possible.
+* They are the backing for almost all Swift Array, Dictionary, and Set objects that you receive from frameworks implemented in Objective-C on Darwin platforms. This may be considered an implementation detail, but it leaks into client code in many ways. We want to provide them here so that your code will remain portable.
+
+##### How do we decide if something belongs in the standard library or Foundation?
+
+In general, the dividing line should be drawn in overlapping area of what people consider the language and what people consider to be a library feature.
+
+For example, Optional is a type provided by the standard library. However, the compiler understands the concept to provide support for things like optional-chaining syntax. The compiler also has syntax for creating Arrays and Dictionaries.
+
+On the other hand, the compiler has no built-in support for types like NSURL. NSURL also has ties into more complex functionality like basic networking support. Therefore this type is more appropriate for Foundation.
+
+##### Why not make the existing Objective-C implementation of Foundation open source?
+
+The Objective-C runtime is not part of the Swift open source project. We can, however, use the open source CoreFoundation implementation. CF is written in C and does not require Objective-C.
+
+##### How do I contribute?
+
+We welcome contributions to Foundation! Please see the [Known Issues](Docs/Issues.md) page if you are looking for an area where we need help. We are also standing by on the [Mailing Lists](https://swift.org/community/#communication) to answer questions about what is most important to do and what we will accept into the project.