[Docs] Various fixes (#2136)

* [Docs] Various fixes * More fixes * Fix ADRs * Typo
2020-08-27 13:27:22 +02:00
parent 2bb585f4fe
commit a8edb19f61
29 changed files with 118 additions and 338 deletions
@@ -12,7 +12,7 @@ Backstage natively supports tracking of the following component
 - Documentation
 - Other

-![](bsc-extend.png)
+![](../../assets/software-catalog/bsc-extend.png)

 Since these types are likely not the only kind of software you will want to
 track in Backstage, it is possible to
@@ -31,9 +31,10 @@ catalog.
 It might be tempting to put software that doesn't fit into any of the existing
 types into Other. There are a few reasons why we advice against this; firstly,
 we have found that it is preferred to match the conceptual model that your
-engineers have when describing your sofware. Secondly, Backstage helps your
-engineers manage their software by integrating the infratrucure tooling through
-plugins. Different plugins are used for managing different types of components.
+engineers have when describing your software. Secondly, Backstage helps your
+engineers manage their software by integrating the infrastructure tooling
+through plugins. Different plugins are used for managing different types of
+components.

 For example, the
 [Lighthouse plugin](https://github.com/spotify/backstage/tree/master/plugins/lighthouse)
@@ -1,6 +1,7 @@
 ---
 id: software-catalog-overview
 title: Backstage Service Catalog (alpha)
+sidebar_label: Backstage Service Catalog
 ---

 ## What is a Service Catalog?
@@ -54,18 +55,18 @@ There are 3 ways to add components to the catalog:
 Users can register new components by going to `/create` and clicking the
 **REGISTER EXISTING COMPONENT** button:

-![](bsc-register-1.png)
+![](../../assets/software-catalog/bsc-register-1.png)

 Backstage expects the full URL to the YAML in your source control. Example:

-```
+```bash
 https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
 ```

 _More examples can be found
 [here](https://github.com/spotify/backstage/tree/master/packages/catalog-model/examples)._

-![](bsc-register-2.png)
+![](../../assets/software-catalog/bsc-register-2.png)

 It is important to note that any kind of software can be registered in
 Backstage. Even if the software is not maintained by your company (SaaS
@@ -83,7 +84,7 @@ registered in the catalog.
 Teams owning the components are responsible for maintaining the metadata about
 them, and do so using their normal Git workflow.

-![](bsc-edit.png)
+![](../../assets/software-catalog/bsc-edit.png)

 Once the change has been merged, Backstage will automatically show the updated
 metadata in the service catalog after a short while.
@@ -92,25 +93,25 @@ metadata in the service catalog after a short while.

 By default the service catalog shows components owned by the team of the logged
 in user. But you can also switch to _All_ to see all the components across your
-companie's software ecosystem. Basic inline _search_ and _column filtering_
-makes it easy to browse a big set of components.
+company's software ecosystem. Basic inline _search_ and _column filtering_ makes
+it easy to browse a big set of components.

-![](bsc-search.png)
+![](../../assets/software-catalog/bsc-search.png)

 ## Starring components

 For easy and quick access to components you visit frequently, Backstage supports
 _starring_ of components:

-![](bsc-starred.png)
+![](../../assets/software-catalog/bsc-starred.png)

 ## Integrated tooling through plugins

-The service catalog is a great way to organise the infrastructure tools you use
+The service catalog is a great way to organize the infrastructure tools you use
 to manage the software. This is how Backstage creates one developer portal for
 all your tools. Rather than asking teams to jump between different
-infrastructure UI’s (and incurring additional cognitive overhead each time they
-make a context switch), most of these tools can be organised around the entities
+infrastructure UIs (and incurring additional cognitive overhead each time they
+make a context switch), most of these tools can be organized around the entities
 in the catalog.

 ![tools](https://backstage.io/blog/assets/20-05-20/tabs.png)
@@ -16,11 +16,13 @@ We model software in the Backstage catalogue using these three core entities
 (further explained below):

 - **Components** are individual pieces of software
+
 - **APIs** are the boundaries between different components
+
 - **Resources** are physical or virtual infrastructure needed to operate a
  component

-![](system-model-core-entities.png)
+![](../../assets/software-catalog/software-model-core-entities.png)

 ### Component

@@ -29,22 +31,22 @@ backend service or data pipeline (list not exhaustive). A component can be
 tracked in source control, or use some existing open source or commercial
 software.

-A component can implement APIs for other components to consume. In turn it
-might depend on APIs implemented by other components, or resources that are
-attached to it at runtime.
+A component can implement APIs for other components to consume. In turn it might
+depend on APIs implemented by other components, or resources that are attached
+to it at runtime.

 ### API

 APIs form an important (maybe the most important) abstraction that allows large
 software ecosystems to scale. Thus, APIs are a first class citizen in the
-Backstage model and the primary way to discover existing functionality in
-the ecosystem.
+Backstage model and the primary way to discover existing functionality in the
+ecosystem.

 APIs are implemented by components and form boundaries between components. They
-might be defined using an RPC IDL (eg Protobuf, GraphQL, ...), a data schema
-(eg Avro, TFRecord, ...), or as code interfaces. In any case, APIs exposed by
-components need to be in a known machine-readable format so we can
-build further tooling and analysis on top.
+might be defined using an RPC IDL (eg Protobuf, GraphQL, ...), a data schema (eg
+Avro, TFRecord, ...), or as code interfaces. In any case, APIs exposed by
+components need to be in a known machine-readable format so we can build further
+tooling and analysis on top.

 APIs have a visibility: they are either public (making them available for any
 other component to consume), restricted (only available to a whitelisted set of
@@ -62,12 +64,13 @@ footprint, and create tooling around them.

 ## Ecosystem Modeling

-A large catalogue of components, APIs and resources can be highly granular
-and hard to understand as a whole. It might thus be convenient to further
-categorize these entities using the following (optional) concepts:
-* **Systems** are a collection of entities that cooperate to perform some
- function
-* **Domains** relate entities and systems to part of the business
+A large catalogue of components, APIs and resources can be highly granular and
+hard to understand as a whole. It might thus be convenient to further categorize
+these entities using the following (optional) concepts:
+
+- **Systems** are a collection of entities that cooperate to perform some
+  function
+- **Domains** relate entities and systems to part of the business

 ### System

@@ -82,15 +85,16 @@ exposes one or several public APIs. The main benefit of modelling a system is
 that it hides its resources and private APIs between the components for any
 consumers. This means that as the owner, you can evolve the implementation, in
 terms of components and resources, without your consumers being able to notice.
-Typically, a system will  consist of at most a handful of components (see
-Domain for a grouping of systems).
+Typically, a system will consist of at most a handful of components (see Domain
+for a grouping of systems).

-For example, a playlist management system might encapsulate a backend service
-to update playlists, a backend service to query them, and a database to store
-them. It could expose an RPC API, a daily snapshots dataset, and an event
-stream of playlist updates.
+For example, a playlist management system might encapsulate a backend service to
+update playlists, a backend service to query them, and a database to store them.
+It could expose an RPC API, a daily snapshots dataset, and an event stream of
+playlist updates.

 ### Domain
+
 While systems are the basic level of encapsulation for related entities, it is
 often useful to group a collection of systems that share terminology, domain
 models, metrics, KPIs, business purpose, or documentation, i.e. they form a