Merge pull request #1271 from spotify/freben-patch-2

docs(catalog-backend): update readme to be more accurate and helpful

docs/README.md

@@ -1,10 +1,10 @@
 # Documentation
 
-Check out <https://backstage.io> or see the table of content below.
+Check out <https://backstage.io> or see the table of contents below.
 
-- [Architecture and terminology](architecture-terminology.md)
-- [Getting started](getting-started/README.md)
+- [Architecture and Terminology](architecture-terminology.md)
+- [Getting Started](getting-started/README.md)
 - [References](reference/README.md)
 - [Publishing](publishing.md)
 - [Designing for Backstage](design.md)
-- [How to add an auth provider](auth/add-auth-provider.md)
+- [How to Add an Auth Provider](auth/add-auth-provider.md)

docs/getting-started/README.md

@@ -1,5 +1,60 @@
 # Getting started with Backstage
 
+## Running Backstage Locally
+
+To get up and running with a local Backstage to evaluate it, let's clone it off
+of GitHub and run an initial build. First make sure that you have at least node
+version 12 installed locally.
+
+```bash
+# Start from your local development folder
+git clone git@github.com:spotify/backstage.git
+cd backstage
+
+# Fetch our dependencies and run an initial build
+yarn install
+yarn tsc
+yarn build
+```
+
+Phew! Now you have a local repository that's ready to run and to add any open
+source contributions into.
+
+We are now going to launch two things: an example Backstage frontend app, and an
+example Backstage backend that the frontend talks to. You are going to need two
+terminal windows, both starting from the Backstage project root.
+
+In the first window, run
+
+```bash
+cd packages/backend
+yarn start
+```
+
+That starts up a backend instance on port 7000.
+
+In the other window, we will first populate the catalog with some nice mock data
+to look at, and then launch the frontend. These commands are run from the
+project root, not inside the backend directory.
+
+```bash
+yarn lerna run mock-catalog-data
+yarn start
+```
+
+That starts up the frontend on port 3000, and should automatically open a
+browser window showing it.
+
+Congratulations! That should be it. Let us know how it went
+[on discord](https://discord.gg/EBHEGzX), file issues for any
+[feature](https://github.com/spotify/backstage/issues/new?labels=help+wanted&template=feature_template.md)
+or
+[plugin suggestions](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME),
+or
+[bugs](https://github.com/spotify/backstage/issues/new?labels=bug&template=bug_template.md)
+you have, and feel free to
+[contribute](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md)!
+
 ## Creating a Plugin
 
 The value of Backstage grows with every new plugin that gets added. Here is a
@@ -7,8 +62,8 @@ collection of tutorials that will guide you through setting up and extending an
 instance of Backstage with your own plugins.
 
 - [Development Environment](development-environment.md)
-- [Create a Backstage plugin](create-a-plugin.md)
-- [Structure of a plugin](structure-of-a-plugin.md)
+- [Create a Backstage Plugin](create-a-plugin.md)
+- [Structure of a Plugin](structure-of-a-plugin.md)
 - [Utility APIs](utility-apis.md)
 - Using Backstage components (TODO)
 

docs/getting-started/create-a-plugin.md

@@ -1,8 +1,8 @@
-# Backstage Plugins
+# Create a Backstage Plugin
 
 A Backstage Plugin adds functionality to Backstage.
 
-## Create a plugin
+## Create a Plugin
 
 To create a new plugin, make sure you've run `yarn install` and installed
 dependencies, then run the following on your command line (invoking the

docs/getting-started/structure-of-a-plugin.md

@@ -1,4 +1,4 @@
-# Structure of a newly created plugin
+# Structure of a Plugin
 
 Nice, you have a new plugin! We'll soon see how we can develop it into doing
 great things. But first off, let's look at what we get out of the box.

plugins/catalog-backend/README.md

@@ -1,16 +1,32 @@
 # Catalog Backend
 
-WORK IN PROGRESS
-
 This is the backend part of the default catalog plugin.
 
-It responds to requests from the frontend part, and fulfills them by delegating
-to your existing catalog related services.
+It comes with a builtin database backed implementation of the catalog, that can store
+and serve your catalog for you.
+
+It can also act as a bridge to your existing catalog solutions, either ingesting their
+data to store in the database, or by effectively proxying calls to an external catalog
+service.
 
 ## Getting Started
 
-After starting the backend, you can issue the `yarn mock-catalog-data` command
-in this directory to populate the catalog with some mock entities.
+This backend plugin can be started in a standalone mode from directly in this package
+with `yarn start`. However, it will have limited functionality and that process is
+most convenient when developing the catalog backend plugin itself.
+
+To evaluate the catalog and have a greater amount of functionality available, instead do
+
+```bash
+# in one terminal window, run this from from the very root of the Backstage project
+cd packages/backend
+yarn start
+
+# open another terminal window, and run the following from the very root of the Backstage project
+yarn lerna run mock-catalog-data
+```
+
+This will launch the full example backend and populate its catalog with some mock entities.
 
 ## Links