Merge pull request #1182 from PowerShell/don/docs

(WIP) Initial draft of repo readme for PM review.

README.md

@@ -1,17 +1,18 @@
-PowerShell
-==========
+![PowerShell Logo](assets/Powershell_64.png) PowerShell
+========================
 
-This repository is "Project Magrathea": Open PowerShell on GitHub, for
-Linux, Windows (.NET Core and Full), and OS X. It is built using the
-[.NET Command Line Interface][dotnet-cli] to support targetting every
-flavor of PowerShell. It is a collaborative effort among many teams:
+PowerShell is a task automation and configuration management platform,
+consisting of a command-line shell and associated scripting language built
+using the [.NET Command Line Interface](https://github.com/dotnet/cli).
+PowerShell provides full access to COM and WMI, enabling administrators to
+automate administrative tasks on both local and remote Windows, Linux and OS X systems.
 
-- Full PowerShell
-- Core PowerShell
-- Open Source Technology Center
-- .NET Foundation
+New to PowerShell?
+------------------
+If you are new to PowerShell and would like to learn more, we recommend
+reviewing the [getting started documentation][getting-started].
 
-[dotnet-cli]: https://github.com/dotnet/cli
+[getting-started]: https://msdn.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell
 
 Build Status
 ------------
@@ -27,54 +28,57 @@ Get PowerShell
 
 |                       | Linux | Windows .NET Core | Windows .NET Full | OS X | PSRP |
 |-----------------------|-------|-------------------|-------------------|------|------|
-| Build from **Source** | [Instructions](docs/building/linux.md) | [Instructions](docs/building/windows-core.md) | [Instructions](docs/building/windows-full.md) | [Instructions](docs/building/osx.md) | [Instructions][psrp] |
-| Get **Binaries**      | [Releases][] | [Releases][] | [Artifacts][] | [Releases][] | TBD |
+| Build from **Source** | [Instructions][build-linux] | [Instructions][build-wc] | [Instructions][build-wf] | [Instructions][build-osx] | [Instructions][pls-omi-provider] |
+| Get **Binaries**      | [Releases][releases] | [Releases][releases] | [Artifacts][artifacts] | [Releases][releases] | TBD |
 
-Building summary: `Start-PSBuild` from the module
-`./build.psm1` (self-host on Linux / OS X)
-
-See [Linux](docs/installation/linux.md) and
-[Windows](docs/installation/windows.md) installation instructions.
+If installing PowerShell from a package, please refer to the installation
+documents for [Linux][inst-linux] and [Windows][inst-win].
 
 [releases]: https://github.com/PowerShell/PowerShell/releases
 [artifacts]: https://ci.appveyor.com/project/PowerShell/powershell/build/artifacts
-[psrp]: https://github.com/PowerShell/psl-omi-provider
+[build-wc]: docs/building/windows-core.md
+[build-wf]: docs/building/windows-full.md
+[build-osx]: docs/building/osx.md
+[build-linux]: docs/building/linux.md
+[pls-omi-provider]: https://github.com/PowerShell/psl-omi-provider
+[inst-linux]: docs/installation/linux.md
+[inst-win]: docs/installation/windows.md
 
-Team coordination
------------------
+Developing and Contributing
+--------------------------
+If you are new to Git, we recommend you start by reviewing our
+[Git basics document][git-basics] where you will find Git installation
+instructions, cheat sheets and links to our favorite Git tutorials. We also
+recommend, reviewing an example of a [basic Git commit walkthrough][git-commit].
 
-- [PSCore Slack chat](https://pscore.slack.com/)
-- [Waffle.io scrum board](https://waffle.io/PowerShell/PowerShell)
-- [VSO items](https://aka.ms/openps)
-- [PowerShell subsystem maintainers](https://aka.ms/psowners)
-- [Automation Sharepoint](https://aka.ms/pscore)
-- [Internal Open PowerShell Documents](https://github.com/PowerShell/Internal-PowerShellTeam-Tools/tree/master/OpenPowerShellDocs)
+To begin development, you'll need to setup your development environment for
+either [Linux][build-linux], [Windows Core][build-wc], [Windows Full][build-wf] or
+[OS X][build-osx] and are encouraged to review the
+[contribution guidelines][contribution] for specific workflow, test
+requirements and coding guidelines.
 
-If you encounter any problems, see the [known issues](KNOWNISSUES.md),
-search the [issues][], and if all else fails, open a new issue.
+If you encounter issues, please consult the [known issues][known-issues]
+and [FAQ][faq] documents to see if the issue you are running into is
+captured and if a workaround exists.  
 
-[issues]: https://github.com/PowerShell/PowerShell/issues
+If do not see your issue captured, please file a [new issue][new-issue] using
+the appropriate issue tag.
 
-Obtain the source code
-----------------------
+[git-basics]: docs/git/basics.md
+[git-commit]: docs/git/committing.md
+[contribution]: .github/CONTRIBUTING.md)
+[known-issues]: docs/KNOWNISSUES.md
+[faq]: docs/FAQ.md
+[new-issue]:https://github.com/PowerShell/PowerShell/issues/new
 
-### Setup Git
 
-Install [Git][], the version control system.
+PowerShell Community
+--------------------
+`TODO` Missing community details
 
-See the [Contributing Guidelines](.github/CONTRIBUTING.md) for more Git
-information, such as our installation instructions, contributing
-rules, and Git best practices.
+Legal and Licensing
+-------------------
 
-[Git]: https://git-scm.com/documentation
+`TODO` Missing license details
 
-### Download source code
-
-Clone this repository. It is a "superproject" and has a number of
-other repositories embedded within it as submodules. *Please* see the
-contributing guidelines and learn about submodules. To make things
-easy, we can just clone recursively.
-
-```sh
-git clone --recursive https://github.com/PowerShell/PowerShell.git
-```
+`TODO` Missing link to contributor agreement