Skip to content

Commit 863265e

Browse files
padraigobrienpadraigobrien
committed
Adding Backstage Techdocs article
1 parent e8eddb1 commit 863265e

206 files changed

Lines changed: 8854 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.jekyll-cache/Jekyll/Cache/Jekyll--Cache/b7/9606fb3afea5bd1609ed40b622142f1c98125abcfe89a76a661b0e8e343910‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
I"�{"source"=>"/Users/podgeobrien/src/docslikecode", "destination"=>"/Users/podgeobrien/src/docslikecode/_site", "collections_dir"=>"", "cache_dir"=>".jekyll-cache", "plugins_dir"=>"_plugins", "layouts_dir"=>"_layouts", "data_dir"=>"_data", "includes_dir"=>"_includes", "collections"=>{"posts"=>{"output"=>true, "permalink"=>"/:categories/:title/"}, "learn"=>{"output"=>true, "permalink"=>"/:collection/:path/"}}, "safe"=>false, "include"=>[".htaccess"], "exclude"=>["_drafts", "lib", "config.rb", "Capfile", "config", "log", "Rakefile", "Rakefile.rb", "tmp", ".less", "*.sublime-project", "*.sublime-workspace", "test", "spec", "Gruntfile.js", "package.json", "node_modules", "Gemfile", "Gemfile.lock", "LICENSE", "README.md", "vendor", ".sass-cache", ".jekyll-cache", "gemfiles", "vendor/bundle/", "vendor/cache/", "vendor/gems/", "vendor/ruby/"], "keep_files"=>[".git", ".svn"], "encoding"=>"utf-8", "markdown_ext"=>"markdown,mkdown,mkdn,mkd,md", "strict_front_matter"=>false, "show_drafts"=>nil, "limit_posts"=>0, "future"=>false, "unpublished"=>false, "whitelist"=>[], "plugins"=>["jekyll-sitemap", "jekyll-gist", "jekyll-feed"], "markdown"=>"kramdown", "highlighter"=>"rouge", "lsi"=>false, "excerpt_separator"=>"\n\n", "incremental"=>false, "detach"=>false, "port"=>"4000", "host"=>"127.0.0.1", "baseurl"=>nil, "show_dir_listing"=>false, "permalink"=>"/:categories/:title/", "paginate_path"=>"/page:num", "timezone"=>nil, "quiet"=>false, "verbose"=>false, "defaults"=>[{"scope"=>{"path"=>"_posts", "type"=>"posts"}, "values"=>{"layout"=>"post", "comments"=>false, "share"=>true}}, {"scope"=>{"path"=>"_learn", "type"=>"learn"}, "values"=>{"layout"=>"post", "comments"=>true, "share"=>true}}], "liquid"=>{"error_mode"=>"warn", "strict_filters"=>false, "strict_variables"=>false}, "kramdown"=>{"auto_ids"=>true, "toc_levels"=>"1..2", "entity_output"=>"as_char", "smart_quotes"=>"lsquo,rsquo,ldquo,rdquo", "input"=>"GFM", "hard_wrap"=>false, "guess_lang"=>true, "footnote_nr"=>1, "show_warnings"=>false, "enable_coderay"=>false, "syntax_highlighter"=>"rouge", "syntax_highlighter_opts"=>{:default_lang=>"plaintext", :guess_lang=>true}, "coderay"=>{}}, "title"=>"Let's Treat Docs Like Code", "locale"=>"en-US", "description"=>"Read stories, learn through practice, share with others.", "logo"=>"/images/treat-docs-like-code.png", "url"=>"https://www.docslikecode.com", "theme"=>"jekyll-theme-so-simple", "search_full_content"=>true, "tag_archive_path"=>"/tags/#", "footer_links"=>[{"title"=>"Twitter", "url"=>"https://twitter.com/annegentle", "icon"=>"fab fa-twitter-square"}, {"title"=>"GitHub", "url"=>"https://github.com/justwriteclick", "icon"=>"fab fa-github-square"}, {"title"=>"Feed", "url"=>"feed.xml", "icon"=>"fas fa-rss-square"}], "google_fonts"=>[{"name"=>"Source Sans Pro", "weights"=>"400,400i,700,700i"}, {"name"=>"Lora", "weights"=>"400,400i,700,700i"}], "google_analytics"=>"UA-85706588-1", "mathjax"=>false, "comments"=>false, "twitter"=>"annegentle", "author"=>{"name"=>"Anne Gentle", "picture"=>"/images/anne_gentle.jpg", "email"=>"annegentle@justwriteclick.com", "disqus-shortname"=>nil, "facebook"=>nil, "github"=>"justwriteclick", "stackexchange"=>nil, "linkedin"=>nil, "instagram"=>nil, "flickr"=>nil, "tumblr"=>nil, "pinterest"=>nil, "weibo"=>nil, "google"=>{"plus"=>"AnneGentle", "verify"=>"LDMHcKG0vxyyo7Tp6hA5xs3_lJYX7Spk9IqC4VZsitE", "ad-client"=>nil, "ad-slot"=>nil}, "bing-verify"=>nil}, "livereload_port"=>35729, "serving"=>true, "watch"=>true}:ET

‎.jekyll-cache/Jekyll/Cache/Jekyll--Converters--Markdown/00/298534448cedb1ad1ff66d56d51dbe2e80371baf41dc056bd43536ad9efacb‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
I"K)<p><strong>Table of contents</strong></p>
2+
3+
<ul>
4+
<li>What is the Scope?
5+
<ul>
6+
<li>Introduction.</li>
7+
<li>Basic concepts and structure of backstage and techdocs.</li>
8+
<li>Install Backstage.</li>
9+
<li>Setup tech docs.</li>
10+
<li>Creating and publishing documentation.</li>
11+
<li>Publish to cloud storage</li>
12+
<li>Recap</li>
13+
</ul>
14+
</li>
15+
</ul>
16+
17+
<h2 id="introduction"><strong>Introduction</strong></h2>
18+
19+
<p>Backstage is a platform for building developer portals.</p>
20+
21+
<p>Its main benefit is allowing you to ship high quality code fast.</p>
22+
23+
<p>The main features you get out of the box are</p>
24+
25+
<ul>
26+
<li>Service catalog.</li>
27+
<li>Software templates.</li>
28+
<li>Plugins which allow you to extend backstage functionality.</li>
29+
<li>Techdocs, which is the focus of this post.</li>
30+
</ul>
31+
32+
<p>These features allow you to create standards and best practices across teams. It increases the speed of development. It creates a good developer experience for everyone who uses it. You centralise all your tools and info in one place.</p>
33+
34+
<p>In this post I will take you through the following</p>
35+
36+
<ul>
37+
<li>Learn basic concepts and structure of backstage and techdocs</li>
38+
<li>Install Backstage</li>
39+
<li>Setup tech docs</li>
40+
<li>Creating and publishing documentation.</li>
41+
<li>All on local machine</li>
42+
</ul>
43+
44+
<h2 id="basics-concepts-and-structures-of-backstage-and-techdocs"><strong>Basics concepts and structures of backstage and techdocs</strong></h2>
45+
46+
<p>The focus of this article is techdocs so i will go through the other main features at a high level.</p>
47+
48+
<ul>
49+
<li>Service catalog. It keeps track of ownership and metadata for all the software in your ecosystem. it does this by putting metadata in YAML files stored together with your code. You process these files and then you can visualise the catalog in backstage. This will enable your teams to manage and maintain the software they own. it also makes the software discoverable.</li>
50+
<li>Software templates - This feature allows you to create templates or skeletons of code. These templates are published to github.</li>
51+
<li>Plugins - Allow you to integrate third part tools or any kind of infrastructure into backstage. They are open source and you can view a list <a href="https://backstage.io/plugins">here</a></li>
52+
<li>Techdocs- yay, finally, why we are here. 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.</li>
53+
</ul>
54+
55+
<p>When you deploy backstage with Techdocs enabled you get a basic out of the box experience.</p>
56+
57+
<p>At its core it is MKDocs plugin and other MkDocs plugins and Python Markdown extensions which allows it to standardize the configuration of MkDocs used for TechDocs.</p>
58+
59+
<p>You can see the code <a href="https://github.com/backstage/mkdocs-techdocs-core">here</a></p>
60+
61+
<p>The other moving parts are</p>
62+
63+
<ul>
64+
<li>The techdocs container which can be found on Docker-hub, It builds static content through MKDocs</li>
65+
<li>The Techdocs backend plugin This is the backend part of the techdocs plugin.</li>
66+
<li>The Techdocs CLI, Command line tool for managing techdocs sites in backstage</li>
67+
<li>The Techdocs reader, it fetch’s remotes pages , run transformers against them and renders them in a shadow DOM</li>
68+
<li>Transformers API is a function that takes in parameters from the reader component and returns a function which gets passed the dom of the fetched page.</li>
69+
</ul>
70+
71+
<p>Architecture</p>
72+
73+
<p><a href="https://backstage.io/docs/assets/techdocs/architecture-basic.drawio.svg">Architecture diagram</a></p>
74+
75+
<p>When you open a techdocs sites a request is made the techdocs reader calls the techdocs-backend with the entity id and the path of the current page, the response contains the static content</p>
76+
77+
<p>The static content contains HTML and CSS, javascript is removed for security reasons</p>
78+
79+
<p>Transforms are then applied which modiy the generated static HTML files for a number of reasons like removing certain headers etc</p>
80+
81+
<p>For the following instructions we will use the local file storage but it is better to use cloud storage like S3.</p>
82+
83+
<h2 id="install-backstage"><strong>Install Backstage</strong></h2>
84+
85+
<p>Perquisites</p>
86+
87+
<p>Node version 14.x</p>
88+
89+
<p>MacOS</p>
90+
91+
<p>cookiecutter</p>
92+
93+
<p>If you already have backstage installed then skip this.</p>
94+
95+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">npx</span> <span class="p">@</span><span class="nd">backstage</span><span class="sr">/create-ap</span><span class="err">p
96+
</span></code></pre></div></div>
97+
98+
<p>You are asked some questions on setup, The recommendation for this tutorial is to go with SQLLite.</p>
99+
100+
<p><img src="/images/techdocs/Untitled.png" alt="/images/techdocs/Untitled.png" /></p>
101+
102+
<p>If successful you will see this message</p>
103+
104+
<p><img src="/images/techdocs/Untitled%201.png" alt="/images/techdocs/Untitled%201.png" /></p>
105+
106+
<p>cd into your directory and run</p>
107+
108+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">yarn</span> <span class="nx">workspace</span> <span class="nx">backend</span> <span class="nx">start</span>
109+
</code></pre></div></div>
110+
111+
<p><img src="/images/techdocs/Untitled%202.png" alt="/images/techdocs/Untitled%202.png" /></p>
112+
113+
<p>Open a new terminal window and</p>
114+
115+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">run</span> <span class="nx">yarn</span> <span class="nx">start</span>
116+
</code></pre></div></div>
117+
118+
<p><img src="/images/techdocs/Untitled%203.png" alt="/images/techdocs/Untitled%203.png" /></p>
119+
120+
<p>If successful a browser window will open up and you should be presented with a window</p>
121+
122+
<p><img src="/images/techdocs/Untitled%204.png" alt="/images/techdocs/Untitled%204.png" /></p>
123+
124+
<p>Well done, you have successfully installed backstage on your machine.</p>
125+
126+
<h2 id="setup-techdocs">Setup TechDocs</h2>
127+
128+
<p>Historically you had to manually add Techdocs , the latest version of create-app bundles tech docs.</p>
129+
130+
<p>to verify this you should be able to see entries for the following plugin</p>
131+
132+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="dl">'</span><span class="s1">@backstage/plugin-techdocs</span><span class="dl">'</span><span class="p">;</span>
133+
134+
</code></pre></div></div>
135+
136+
<p>in the following files</p>
137+
138+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">packages</span><span class="o">/</span><span class="nx">app</span><span class="o">/</span><span class="nx">src</span><span class="o">/</span><span class="nx">plugins</span><span class="p">.</span><span class="nx">ts</span>
139+
<span class="nx">packages</span><span class="o">/</span><span class="nx">app</span><span class="o">/</span><span class="nx">src</span><span class="o">/</span><span class="nx">App</span><span class="p">.</span><span class="nx">tsx</span>
140+
</code></pre></div></div>
141+
142+
<h2 id="creating-and-publishing-techdocs">Creating and publishing techdocs</h2>
143+
144+
<p>To create docs manually from scratch click on create component</p>
145+
146+
<p><img src="/images/techdocs/Untitled%205.png" alt="/images/techdocs/Untitled%205.png" /></p>
147+
148+
<p>From here choose the Documentation template</p>
149+
150+
<p><img src="/images/techdocs/Untitled%206.png" alt="/images/techdocs/Untitled%206.png" /></p>
151+
152+
<p>Fill out Name and Description</p>
153+
154+
<p><img src="/images/techdocs/Untitled%207.png" alt="/images/techdocs/Untitled%207.png" /></p>
155+
156+
<p>Type in the owner, the Github repo you want to call it , ensure their is no Github repo that exists with the same name or the Templater will fail</p>
157+
158+
<p><img src="/images/techdocs/Untitled%208.png" alt="/images/techdocs/Untitled%208.png" /></p>
159+
160+
<p>Once you click on create you will be presented with a Create component status popup.</p>
161+
162+
<p><img src="/images/techdocs/Untitled%209.png" alt="/images/techdocs/Untitled%209.png" /></p>
163+
164+
<p>Once the repository has been published to github the create component status popup will go green like below.</p>
165+
166+
<p><img src="/images/techdocs/Untitled%2010.png" alt="/images/techdocs/Untitled%2010.png" /></p>
167+
168+
<p>You will be able to navigate to the docs.</p>
169+
170+
<p><img src="/images/techdocs/Untitled%2011.png" alt="/images/techdocs/Untitled%2011.png" /></p>
171+
172+
<p>If it is the first time you are loading them you could receive this message while it converts from MD to html</p>
173+
174+
<p><img src="/images/techdocs/Untitled%2012.png" alt="/images/techdocs/Untitled%2012.png" /></p>
175+
176+
<p>Here is what you will be presented with.</p>
177+
178+
<p><img src="/images/techdocs/Untitled%2013.png" alt="/images/techdocs/Untitled%2013.png" /></p>
179+
180+
<p>You now have techdocs up and running on your machine, if you want to view the files manually they are located at the following location on you machine</p>
181+
182+
<div class="language-jsx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">backstage</span><span class="o">/</span><span class="nx">node_modules</span><span class="o">/</span><span class="p">@</span><span class="nd">backstage</span><span class="sr">/plugin-techdocs-backend/</span><span class="kd">static</span><span class="sr">/docs/</span><span class="k">default</span><span class="sr">/Component/</span>
183+
</code></pre></div></div>
184+
185+
<p>The recommended setup is to place the output on to cloud storage and not on the local machine</p>
186+
187+
<h2 id="publish-to-cloud-storage">Publish to cloud storage</h2>
188+
189+
<p><img src="/images/techdocs/Untitled%2014.png" alt="/images/techdocs/Untitled%2014.png" /></p>
190+
191+
<p><img src="/images/techdocs/Untitled%2015.png" alt="/images/techdocs/Untitled%2015.png" /></p>
192+
193+
<p><img src="/images/techdocs/Untitled%2016.png" alt="/images/techdocs/Untitled%2016.png" /></p>
194+
195+
<h2 id="recap">Recap</h2>
196+
197+
<p>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 <a href="https://backstage.io">https://backstage.io</a> or if you want to learn more about techdocs then <a href="https://backstage.io/docs/features/techdocs/techdocs-overview">https://backstage.io/docs/features/techdocs/techdocs-overview</a></p>
198+
199+
<p>If you like the idea of backstage but don’t want the inconvenience of managing backstage yourself then i would check out Roadie.io.</p>
200+
:ET

‎.jekyll-cache/Jekyll/Cache/Jekyll--Converters--Markdown/00/c29ba6474ab5899ab0748c16c5b71dce4316c8eefacf6bc7fbb5d389c0a3e8‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
I"�<h1>Get Started with Docs as Code</h1>
2+
3+
<p><img src="../../images/docs-like-code-book.jpg" alt="Docs Like Code" style="padding:14px;" align="right" height="200" width="319" /></p>
4+
<p>We've transformed the way teams work together on docs, and we want to show you the best practices for writing docs using development tools and techniques. Now available in both print and ebook, check out <i>Docs Like Code</i>.</p>
5+
6+
<p><a href="https://www.lulu.com/spotlight/justwriteclick" style="display: inline-block;
7+
margin-bottom: 20px;
8+
padding: 8px 20px;
9+
font-size: 14px;
10+
background-color: #fc5720;
11+
color: #fff;
12+
border: 2px solid #fc5720 !important;
13+
border-radius: 3px;
14+
&amp;:visited {
15+
color: #fff;
16+
}
17+
&amp;:hover {
18+
background-color: #fff;
19+
color: #64baaa;"><i class="fa fa-book"></i> Buy Now</a></p>
20+
21+
<h1>What's inside?</h1>
22+
23+
<p><strong>Why use GitHub for docs?</strong> If you're unsure of a good fit for your projects and teams, read about the potential wins with these techniques. Or, you may learn how to convince others who need to hear about the use cases.</p>
24+
<p><strong>Information architecture and workflows, how do you choose?</strong> Read these chapters to find out lessons learned when making sure the users are served first.
25+
</p>
26+
<p>
27+
<strong>How can I improve upon my team's work?</strong> Author and build content like a pro, whether you're a writer or a developer. Build in quality assurance, automate builds, and review with your teammates to make great docs.
28+
</p>
29+
<p>
30+
<strong>What are the best practices for REST API docs?</strong> While Swagger/OpenAPI, RAML, and other standards work well when considering the entire API lifecycle, you can also consider collaboration gains with simple markup and narrative documents beyond the REST API reference doc set.
31+
</p>
32+
33+
<p><a href="https://www.lulu.com/spotlight/justwriteclick" style="display: inline-block;
34+
margin-bottom: 20px;
35+
padding: 8px 20px;
36+
font-size: 14px;
37+
background-color: #fc5720;
38+
color: #fff;
39+
border: 2px solid #fc5720 !important;
40+
border-radius: 3px;
41+
&amp;:visited {
42+
color: #fff;
43+
}
44+
&amp;:hover {
45+
background-color: #fff;
46+
color: #fc5720;"><i class="fa fa-book"></i> Buy Now</a></p>
47+
48+
<h1>Who's using these techniques?</h1>
49+
50+
<blockquote>
51+
<p>“I met with one of the devs today to go over a Pull Request that I had submitted with editorial comments, and in the course of conversation, I mentioned that I had not been working directly with developers for very long.</p>
52+
53+
<p>He replied that he’d worked with technical editors in the past who were not very helpful, but that I was different. In fact, he assumed I was a developer at first because I was working in GitHub, effortlessly creating PRs!”
54+
<br />
55+
— <em>Kelly Holcomb, Senior Technical Editor, Rackspace</em></p>
56+
</blockquote>
57+
58+
<blockquote>
59+
<p>“This book will be the go-to guide for people looking to get into the <em>Docs like Code</em> world. It has been on my list to write for a while, and I’m glad someone did for me. :)”
60+
<br />
61+
— Eric Holscher, Cofounder of Read the Docs and Write the Docs</p>
62+
</blockquote>
63+
64+
<p><a href="https://www.lulu.com/spotlight/justwriteclick" style="display: inline-block;
65+
margin-bottom: 20px;
66+
padding: 8px 20px;
67+
font-size: 14px;
68+
background-color: #fc5720;
69+
color: #fff;
70+
border: 2px solid #fc5720 !important;
71+
border-radius: 3px;
72+
&amp;:visited {
73+
color: #fff;
74+
}
75+
&amp;:hover {
76+
background-color: #fff;
77+
color: #ffc858;"><i class="fa fa-book"></i> Buy Now</a></p>
78+
79+
<blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">Just finished <a href="https://twitter.com/annegentle">@annegentle</a>&#39;s new book, Docs Like Code, and it&#39;s outstanding for devs. If you value quality docs, see <a href="https://t.co/pVbhOcB3Bx">https://t.co/pVbhOcB3Bx</a></p>&mdash; Carol Willing (@WillingCarol) <a href="https://twitter.com/WillingCarol/status/836990174601101313">March 1, 2017</a></blockquote>
80+
<script async="" src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
81+
82+
<blockquote class="twitter-tweet" data-conversation="none" data-lang="en"><p lang="en" dir="ltr"><a href="https://twitter.com/annegentle">@annegentle</a> My trick? Treating docs like code! 😉<a href="https://t.co/NuuTgJcs3M">https://t.co/NuuTgJcs3M</a></p>&mdash; Carolyn Van Slyck (@carolynvs) <a href="https://twitter.com/carolynvs/status/840775351299145728">March 12, 2017</a></blockquote>
83+
<script async="" src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
84+
85+
<blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">Just finished &quot;Docs Like Code&quot; by <a href="https://twitter.com/annegentle">@annegentle</a> - Superb advice for modern technical writing. <a href="https://t.co/jI9jsA0OIy">https://t.co/jI9jsA0OIy</a></p>&mdash; Doug Hellmann (@doughellmann) <a href="https://twitter.com/doughellmann/status/838911867338772480">March 7, 2017</a></blockquote>
86+
<script async="" src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
87+
88+
<blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">This one just moved to the top of my reading list. A book on how to treat docs like code by <a href="https://twitter.com/annegentle">@annegentle</a>. Awesome! &gt; <a href="https://t.co/nRkSZkhv5x">https://t.co/nRkSZkhv5x</a></p>&mdash; Patrick Andriessen (@napnamPat) <a href="https://twitter.com/napnamPat/status/838695213841403904">March 6, 2017</a></blockquote>
89+
<script async="" src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
90+
91+
:ET

‎.jekyll-cache/Jekyll/Cache/Jekyll--Converters--Markdown/01/50f63e9f6395446958c102146ed0b7a99e7a1a9eed3d6111bfa5adabc1cdaf‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
I"G<p>From Mandy Whaley’s presentation at All Day DevOps 2017.</p>
2+
:ET

‎.jekyll-cache/Jekyll/Cache/Jekyll--Converters--Markdown/01/ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
I"
2+
:ET

‎.jekyll-cache/Jekyll/Cache/Jekyll--Converters--Markdown/02/5828285dba30d7c544eda1301b9ff258c0fd8d8b33c4771af9af62a5d40e19‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
I"4<p>Evaluating table layouts and formatting</p>
2+
:ET

0 commit comments

Comments
 (0)