microsite-next: Add experimental microsite with CI workflow

Signed-off-by: Johan Haals <johan.haals@gmail.com>
2022-12-12 15:32:06 +01:00
parent a48cfaa653
commit 8fd7c81594
15 changed files with 11055 additions and 9 deletions
@@ -23,12 +23,12 @@ Spotify’s developers were facing three big challenges on a daily basis:
 - They needed to keep an eye on what squads around them might be building to ensure they could reuse systems when they needed to solve similar problems in the future.

 In short, Spotify developers needed to continue building industry leading features at breakneck speed, while simultaneously maintaining a mental model for all the software at Spotify (oh, and help every new joiner develop that mental model as well!).
-<br>
+<br/>

 ## Three jobs: Create, manage, explore

 Around the same time, the [jobs to be done](https://hbr.org/2016/09/know-your-customers-jobs-to-be-done) framework was becoming popular and luckily, a few Spotifiers helped guide the vision for a _sense-making tool for developers_ toward using it. After user research and many failed attempts, we landed on three jobs Spotify developers needed to do consistently:
-<br>
+<br/>

 - **Create**: Spotify developers want to delight their customers with incredible features. They create new software to do that.
 - **Manage**: Spotify developers are proud of their work and treat their software and data like products. That requires maintaining all the software they own on an ongoing basis.
@@ -73,7 +73,7 @@ Within today’s complex development environments, there are barriers both big a
 After talking with companies who have already adopted Backstage, we’ve seen a few common strategies for getting started. The different strategies are based on the size of your engineering org (which often also corresponds with how fast you’re growing).

 ![200 engineers](assets/21-05-20/200-engineers_v.2.png)
-<br>
+<br/>

 ### My org has ~200 engineers (and is growing fast)

@@ -21,9 +21,7 @@ When we set out to define what beta looked like, we combed through GitHub issues

 TechDocs can be transformational once fully up and running (update your code and your docs with the same pull request!). But for first-time users and especially those unfamiliar with the MkDocs ecosystem upon which TechDocs is built, there are often many small, obtuse hurdles that can get in the way of success. Leading up to the beta release, we worked to surface and improve relevant errors and other details during the documentation generation process. Better still, all of this detail is now provided to users _in real-time_, as docs are generated and refreshed.

-<!-- vale off -->
 <p>🙌 Shout out to <a href="https://github.com/dhenneke">Dominik Henneke</a> for implementing the interactive experience.</p>
-<!-- vale on -->

 ## Custom homepages: Make TechDocs yours

@@ -31,9 +29,7 @@ TechDocs can be transformational once fully up and running (update your code and

 We strive to make it so that you can mold Backstage into the shape that best fits your organization. With this beta release, just as you can with the Catalog entities and [Search](https://backstage.io/blog/2021/06/24/announcing-backstage-search-platform#composable-search-page-experiences), you can now customize and compose your own TechDocs homepage. Use it to level up the front page of your Backstage documentation by highlighting golden documentation at your company, or use the new and improved (and Catalog-inspired) experience. Read more about [how to customize the TechDocs homepage](https://backstage.io/docs/features/techdocs/how-to-guides#how-to-customize-the-techdocs-home-page).

-<!-- vale off -->
 <p>🙏 Thanks to <a href="https://github.com/kuangp">Phil Kuang</a> for the improved default TechDocs home experience.</p>
-<!-- vale on -->

 ## Simpler YAML annotations: What's in a ref?

@@ -43,9 +39,7 @@ We often forget that in order to enable TechDocs on a Catalog entity, documentat

 In the beta, we've simplified this annotation dramatically for documentation authors, aligning its value with TechDocs' docs-like-code philosophy itself. In the vast majority of cases, its value will simply be `dir:.` — which means this catalog entity contains documentation and the mkdocs.yml file describing this documentation lives in the current directory. We continue to support edge cases for [other techdocs-ref annotation values](https://backstage.io/docs/features/techdocs/how-to-guides#how-to-understand-techdocs-ref-annotation-values), as well.

-<!-- vale off -->
 <p>👏 Another round of applause for Dominik for driving this improvement through.</p>
-<!-- vale on -->

 ## Everything neat and tidy