improved documentation in README.md files

README.md

@@ -3,4 +3,88 @@ FSharp.ProjectScaffold
 
 A prototypical F# library (file system layout and tooling), recommended by the F# Foundation.
 
-[Reference documents available here](http://pblasucci.github.io/FSharp.ProjectScaffold)
+Overview
+---
+
+This sample demonstrates the suggested structure of a typical F# solution.
+_(NOTE: this layout should NOT be used when authoring a Type Provider. 
+For more details about doing so, see [read this.](http://link/needed))_
+
+The general structure (on-disk) is laid out below,
+followed by a detailed description. 
+
+-	.nuget/
+	*	Nuget.config
+	*	Nuget.exe
+	*	Nuget.targets
+	*	packages.config
+-	bin/
+	*	[README.md](http://link/needed)
+-	docs/
+	-	content/
+		*	index.fsx
+		*	tutorial.fsx
+	-	files/
+		-	img/
+			*	logo.png
+	+	output/
+	-	tools/
+		-	templates/
+			*	template.cshtml
+		*	generate.fsx
+		*	packages.config
+-	lib/
+	*	[README.md](http://link/needed)
+-	nuget/
+-	packages/
+	*	[README.md](http://link/needed)
+-	src/
+	+	FSharp.ProjectTemplate/
+-	temp/
+	*	[README.md](http://link/needed)
+-	tests/
+	+	FSharp.ProjectTemplate.Tests/
+*	build.cmd
+*	build.fsx
+*	FSharp.ProjectScaffold.sln
+*	[LICENSE.txt](http://link/needed)
+*	[RELEASE_NOTES.md](http://link/needed)
+*	[README.md](http://link/needed)
+
+<table>
+	<caption>Summary of solution folders</caption>
+	<thead>
+		<tr>
+			<td>Folder</td>
+			<td>Descritpion</td>
+		</tr>
+	</thead>
+	<tbody>
+		<tr>
+			<td></td>
+			<td></td>
+		</tr>
+	</tbody>
+</table>
+
+<table>
+	<caption>Summary of important solution files</caption>
+	<thead>
+		<tr>
+			<td>Path</td>
+			<td>File</td>
+			<td>Descritpion</td>
+		</tr>
+	</thead>
+	<tbody>
+		<tr>
+			<td></td>
+			<td></td>
+			<td></td>
+		</tr>
+	</tbody>
+</table>
+
+---
+
+[Sample API documents available here](http://pblasucci.github.io/FSharp.ProjectScaffold)

RELEASE_NOTES.md

@@ -1,2 +1,3 @@
 * 0.0.0-beta - Initial release
 * 0.0.1-beta - Changed name from fsharp-project-scaffold to FSharp.ProjectScaffold
+* 0.5.0-beta - Improved quality of solution-wide README.md files

nuget/README.md

@@ -1,2 +1,11 @@
+This file is in the `nuget` directory.
+You should use this directory to store any artifacts required to produce a NuGet package for your project.
+This typically includes a `.nuspec` file and some `.ps1` scripts, for instance.
+Additionally, this example project includes a `.cmd` file suitable for manual deployment of packages to http://nuget.org.
+
+---
+NOTE: 
+
 This file is a placeholder, used to preserve directory structure in Git.
-It does not need to be edited.
+
+This file does not need to be edited.

packages/README.md

@@ -1,2 +1,13 @@
+This file is in the `packages` directory.
+Any NuGet packages on which your project depends will be downloaded to this directory.
+Additionally, packages required by the build process will be stored here.
+
+It is **strongly advised** that the **contents of this directory not be committed** to source control 
+(with the sole exception being this `README.md` file).
+
+---
+NOTE: 
+
 This file is a placeholder, used to preserve directory structure in Git.
-It does not need to be edited.
+
+This file does not need to be edited.