Roadie by padraigobrien · Pull Request #167 · justwriteclick/docslikecode

padraigobrien · 2021-02-15T20:14:07Z

A simple tutorial on how to get started with backstage and techdocs

annegentle

I'm so glad to get this additional technical description of Backstage and TechDocs! I had a power outage and Internet outage (due to snow ❄️ in Texas!) so it'll take me at least another day to get through this, but wanted to say I'm reading and like what I see.

padraigobrien · 2021-02-16T08:42:54Z

Thanks Anne, looking forward to more feedback

annegentle · 2021-02-21T05:40:17Z

Hi @padraigobrien - great stuff! I was able to get it working (finally after many power outages and no Internet). Now I have a bunch of updates locally that I want to patch your PR with, is that okay with you? That was easier than doing line-by-line comments.

padraigobrien · 2021-02-22T17:41:00Z

@annegentle totally, let me know if i can help

dtuite

Overall I think the content is suitable and will help people get set up with TechDocs on Backstage.

It needs a thorough proof-read and edit.

dtuite · 2021-03-01T09:55:43Z

+title: Setting up Techdocs on Backstage
+excerpt: "Techdocs is Spotify's homegrown docs like code solution. it allows the user to store documentation to near code thus allowing it to be easily discovered."
+last_modified_at: Sun Feb  12 14:39:05 CST 2021
+categories: articles


It would make more sense to put this in the Learn section of the site because it's a tutorial.

I debated this point myself, but came out on the article side because there's some precedence set there and better findability evidence. Based on GA, a couple of the more popular articles on the site are https://www.docslikecode.com/articles/balsamiq-case-study-part-2/ and https://www.docslikecode.com/articles/api-docs-with-code/, probably because the keywords are super relevant. I can move it over though if you feel strongly about it.

dtuite · 2021-03-01T09:59:12Z

+comments: false
+share: true
+---
+TechDocs is Spotify’s homegrown docs-like-code solution built directly into Backstage. This means engineers write their documentation in Markdown files which live together with their code. In this post we will walk you through how to setup Backstage and Techdocs.


Would it make more sense to explain what Backstage is, rather than explaining what docs-like-code is?

I would expect the reader to be familiar with docs-like-code since they're on this site in the first place. They may not know about Backstage. It might be useful to link to this article written by one of the TechDocs team at Spotify.

Great minds think alike! I linked to it in the summary, I'll move the link to here.

dtuite · 2021-03-01T09:59:58Z

+
+Its main benefit is allowing you to ship high quality code fast.
+
+The main features you get out of the box are


remove reuse of the word "main"

dtuite · 2021-03-01T10:00:25Z

+
+## **Basics concepts and structures of backstage and techdocs**
+
+The focus of this article is techdocs so i will go through the other main features at a high level.


Capitalize I

dtuite · 2021-03-01T10:02:56Z

+
+The other moving parts are
+
+- The techdocs container which can be found on Docker-hub, It builds static content through MKDocs


Is it worth linking to docker hub?

dtuite · 2021-03-01T10:12:56Z

+
+![owner](/images/techdocs/08.png)
+
+Once you click on create you will be presented with a Create component status popup.


This will fail unless the user has a GITHUB_TOKEN set. They haven't been instructed to do this anywhere in the tutorial. I think this needs to be covered.

Once this PR is merged we will have a dedicated tutorial available for generating the GITHUB_TOKEN. Perhaps we could link this in the post?

dtuite · 2021-03-01T10:14:15Z

+
+The recommended setup is to place the output on to cloud storage and not on the local machine
+
+## Publish to cloud storage


I think we either need to omit this section and cover cloud storage elsewhere, or explain to the reader that they need to create a storage bucket.

dtuite · 2021-03-01T10:15:21Z

+
+In summary, we went through an introduction on backs stage, techdocs and how to publish techdocs locally and to cloud storage via s3. if you want to learn more about backstage i would recommend visiting [https://backstage.io](https://backstage.io) or if you want to learn more about techdocs then [https://backstage.io/docs/features/techdocs/techdocs-overview](https://backstage.io/docs/features/techdocs/techdocs-overview)
+
+If you like the idea of backstage but don't want the inconvenience of managing backstage yourself then i would check out   [https://roadie.io](https://roadie.io).


The subject of this sentence changes from "you" to "i" part way through.

dtuite · 2021-03-01T10:16:39Z

+
+## Recap
+
+In summary, we went through an introduction on backs stage, techdocs and how to publish techdocs locally and to cloud storage via s3. if you want to learn more about backstage i would recommend visiting [https://backstage.io](https://backstage.io) or if you want to learn more about techdocs then [https://backstage.io/docs/features/techdocs/techdocs-overview](https://backstage.io/docs/features/techdocs/techdocs-overview)


There are a number of capitalization typos in this paragraph.

dtuite · 2021-03-01T10:17:15Z

+  picture: http://docslikecode.com/images/padraig_o_brien.jpg
+  github: //github.com/padraigobrien
+  twitter: padraigobrien
+  bio: "Director of engineering"


The build is failing because of a missing newline.

annegentle · 2021-03-01T15:17:19Z

Thanks @dtuite! I've got another PR that does the full edit but I hadn't caught the missing newline, nice! Good catch. I'll get this working and hopefully published this week.

padraigobrien added 4 commits February 15, 2021 20:01

Adding Backstage Techdocs article

863265e

Adding Backstage Techdocs article

870fbc9

Adding Backstage Techdocs article

009226f

Adding Backstage Techdocs article

07cad17

annegentle reviewed Feb 16, 2021

View reviewed changes

dtuite suggested changes Mar 1, 2021

View reviewed changes

annegentle changed the base branch from main to build March 1, 2021 16:02

annegentle merged commit 6038166 into justwriteclick:build Mar 1, 2021


		Its main benefit is allowing you to ship high quality code fast.

		The main features you get out of the box are


		## Basics concepts and structures of backstage and techdocs

		The focus of this article is techdocs so i will go through the other main features at a high level.


		The other moving parts are

		- The techdocs container which can be found on Docker-hub, It builds static content through MKDocs


		![owner](/images/techdocs/08.png)

		Once you click on create you will be presented with a Create component status popup.


		The recommended setup is to place the output on to cloud storage and not on the local machine

		## Publish to cloud storage


		In summary, we went through an introduction on backs stage, techdocs and how to publish techdocs locally and to cloud storage via s3. if you want to learn more about backstage i would recommend visiting [https://backstage.io](https://backstage.io) or if you want to learn more about techdocs then [https://backstage.io/docs/features/techdocs/techdocs-overview](https://backstage.io/docs/features/techdocs/techdocs-overview)

		If you like the idea of backstage but don't want the inconvenience of managing backstage yourself then i would check out [https://roadie.io](https://roadie.io). No newline at end of file


		## Recap

		In summary, we went through an introduction on backs stage, techdocs and how to publish techdocs locally and to cloud storage via s3. if you want to learn more about backstage i would recommend visiting [https://backstage.io](https://backstage.io) or if you want to learn more about techdocs then [https://backstage.io/docs/features/techdocs/techdocs-overview](https://backstage.io/docs/features/techdocs/techdocs-overview)

Conversation

padraigobrien commented Feb 15, 2021

Uh oh!

annegentle left a comment

Choose a reason for hiding this comment

Uh oh!

padraigobrien commented Feb 16, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

annegentle commented Feb 21, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

padraigobrien commented Feb 22, 2021

Uh oh!

dtuite left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

annegentle commented Mar 1, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

padraigobrien commented Feb 16, 2021 •

edited

Loading

annegentle commented Feb 21, 2021 •

edited

Loading