Move internal docs to public location (#8838)

This streamlines our README and moves docs from our internal OneNote to the git repo. The hope is to make it easier for the community to contribute to NuGet Gallery for up-for-grab items like #8837.

Author: loic-sharma

README.md

@@ -1,53 +1,30 @@
-[NuGet Gallery](http://nuget.org/) — Where packages are found 
+[NuGet Gallery](https://www.nuget.org/) — Where packages are found 
 =======================================================================
 
-This is an implementation of the NuGet Gallery and API. This serves as the back-end and community 
-website for the NuGet client. For information about the NuGet project, visit the [Home repository](https://github.com/nuget/home).
+This  project powers [nuget.org](https://www.nuget.org), the home for .NET's open-source ecosystem. For information about NuGet, visit the [Home repository](https://github.com/nuget/home).
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
 
-## Build and Run the Gallery in (arbitrary number) easy steps
+## Getting started
 
-1. Prerequisites:
-    1. Visual Studio 2019 - Install the following `Workloads`:
-        * ASP.NET and web development
-        * Azure development
-    2. PowerShell 4.0
-    3. SQL Server 2016
-        * For development purposes connection strings point to `(localdb)\mssqllocaldb`, make sure that the DB engine version 13.0 or greater is being used (check by running `sqllocaldb info mssqllocaldb` in the command line).
-2. Clone it!
-    
-    ```PS C:\Code> git clone https://github.com/NuGet/NuGetGallery.git```
-3. Build it!
-    
-    ```
-    PS C:\Code> cd NuGetGallery
-    PS C:\Code\NuGetGallery> .\build
-    ```
-4. Set up the website!
+First install prerequisites:
 
-    ```PS C:\Code\NuGetGallery> .\tools\Setup-DevEnvironment.ps1```
-    
-5. If you would like to configure your gallery instance to use MSA/AAD, please follow the steps listed [here](https://github.com/NuGet/NuGetGallery/wiki/Configuring-MSA-AAD-for-your-on-prem-gallery-instance).
+1. Visual Studio 2019 - Install the following [`Workloads`](https://docs.microsoft.com/visualstudio/install/modify-visual-studio):
+    * ASP.NET and web development
+    * Azure development
+2. PowerShell 4.0
+3. SQL Server 2016 (with DB engine version 13.0 or greater)
 
-6. Ensure the `NugetGallery` project is the StartUp Project and press `F5` to run the site! That's it!
+Now run the NuGet Gallery:
 
-When working with the gallery, e-mail messages are saved to the file system (under `~/App_Data`).
-You can use an SMTP server instead by editing `src\NuGetGallery\Web.Config` and adding a `Gallery.SmtpUri`
-setting. Its value should be an SMTP connection string, such as: `smtp://user:password@smtpservername:25`.
-You can also turn off e-email confirmations by changing the value of `Gallery.ConfirmEmailAddresses` to `false`
-in the `src\NugetGallery\Web.Config` file.
+1. Clone the repository with `git clone https://github.com/NuGet/NuGetGallery.git`
+2. Navigate to `.\NuGetGallery`
+3. Build with `.\build.ps1`
+4. Create the database and enable HTTPS with `.\tools\Setup-DevEnvironment.ps1`
+5. Open `.\NuGetGallery.sln` using Visual Studio
+6. Ensure the `NuGetGallery` project is the StartUp Project and [press `F5` to run the site](https://docs.microsoft.com/visualstudio/get-started/csharp/run-program)
 
-Visual Studio may modify the `applicationhost.config` file. You can force git to ignore changes to this file
-with:
-
-    git update-index --assume-unchanged .vs/config/applicationhost.config
-
-You can undo this with this command:
-
-    git update-index --no-assume-unchanged .vs/config/applicationhost.config
-
-This should help prevent unwanted file commits.
+Refer to [our documentation](./docs/) for information on how to develop the frontend, use AAD, and more.
 
 ## Deploy
 
@@ -94,6 +71,17 @@ This is the Git workflow we're currently using:
 
 Clone and checkout the `dev` branch.
 
+Visual Studio may modify the `applicationhost.config` file. You can force git to ignore changes to this file
+with:
+
+    git update-index --assume-unchanged .vs/config/applicationhost.config
+
+You can undo this with this command:
+
+    git update-index --no-assume-unchanged .vs/config/applicationhost.config
+
+This should help prevent unwanted file commits.
+
 ### When starting a new feature/unit of work.
 
 1.  __Pull the latest.__
@@ -146,3 +134,4 @@ Clone and checkout the `dev` branch.
 
 6.  __Be ready to guide your change through QA, Staging and Prod__
     Your change will make its way through the QA, Staging and finally Prod branches as it's deployed to the various environments. Be prepared to fix additional bugs!
+

docs/Emails.md

@@ -0,0 +1,9 @@
+# Emails
+
+By default, the Gallery saves e-mail messages to the file system under `src\NuGetGallery\App_Data`.
+
+You can use an SMTP server instead by editing `src\NuGetGallery\Web.config` and adding a `Gallery.SmtpUri`
+setting. Its value should be an SMTP connection string, such as `smtp://user:password@smtpservername:25`.
+
+You can require new accounts confirm their e-mail adddress by changing the value of `Gallery.ConfirmEmailAddresses`
+to `true` in the `src\NuGetGallery\Web.config` file.

docs/Frontend.md

@@ -0,0 +1,42 @@
+# Updating NuGet Gallery's frontend
+
+## Styling
+
+We use [Bootstrap 3](https://getbootstrap.com/docs/3.3/) as our base CSS framework.
+This provides a grid layout, CSS normalization, and some common styles.
+
+Changes to our styles should be made to [LESS](https://lesscss.org/) files and not to a CSS file directly.
+LESS is a syntax that itself is not usable by a browser but is compiled to CSS. It provides niceties that CSS
+does not offer such as rule nesting, mixins, variables, and arithmetic (calculated values).
+
+Each page may have its own set of specific styles. These page-specific styles are in a `page-*.less` file
+in the `src\Bootstrap\less\theme\` directory.
+
+### Prerequisites
+
+To compile LESS files:
+
+1. Install node: https://nodejs.org/en/download/
+1. Install Grunt: `npm install -g grunt`
+1. Navigate to `.\src\Bootstrap`
+1. Install NPM dependencies: `npm install`
+
+### Updating styling
+
+1. Update one or more `.less` files in the `src\Bootstrap\less` directory
+1. Navigate to `.\src\Bootstrap`
+1. Run `grunt`
+
+### Adding a new page
+
+1. Create a new `page-X.less` file in the `src\Bootstrap\less\theme\` directory
+1. Add the new page in `src\Bootstrap\less\theme\all.less`
+
+## JavaScript
+
+We use [jQuery](https://jquery.com/) and [Knockout.js](https://knockoutjs.com/).
+
+Common JavaScript should be added to `src\NuGetGallery\Scripts\gallery\common.js`.
+
+Each page may have its own custom logic. These page-specific scripts are in a `page-*.js` file
+in the `src\NuGetGallery\Scripts\gallery\` directory.

docs/README.md

@@ -2,5 +2,7 @@
 
 You can find documentation for:
 
+1. [Updating NuGet Gallery's frontend](Frontend.md)
 1. [Building, deploying, and managing a NuGet Gallery instance](Deploying/README.md)
-1. [Using Azure Active Directory authentication](Using-AAD.md)
+1. [Email configuration](Emails.md)
+1. [Using Azure Active Directory authentication](Using-AAD.md)