Add Gary Niemen's article, Ten tips for maintaining a long-term relationship with docs like code#159
Add Gary Niemen's article, Ten tips for maintaining a long-term relationship with docs like code#159annegentle merged 6 commits intobuildfrom
Conversation
…elationship with docs like code
| <!-- By Gary Niemen, Product Manager for TechDocs, Spotify’s docs-like-code solution --> | ||
|
|
||
| I remember about two years ago sitting here watching a Write the Docs video. Well, not precisely “here” because we sat in offices in those days and in 2020 I'm in my home office working for Spotify. If you haven't heard of it, Spotify is a digital music, podcast, and video streaming service providing access to content from artists around the world. I was watching, wide-eyed and a bit confused, a video of [Riona MacNamara’s talk from Write the Docs 2015](https://youtu.be/EnB8GtPuauw). In the talk, Riona described how she and another technical writer used a docs-like-code approach to change Google engineering culture around technical documentation. | ||
|
|
There was a problem hiding this comment.
I split the lead into three sentences and I added a description of what Spotify is with, "If you haven't heard of it, Spotify is a digital music, podcast, and video streaming service providing access to content from artists around the world." I paraphrased from a support article so hopefully your review folks will still approve. :)
There was a problem hiding this comment.
Good catch. I am normally good on giving people the right context - but I had totally forgotten that piece. I have read through this paragraph a few times. I am not sure it flows 100% because I was working for Spotify back then as well and it reads like I have recently joined. But perhaps I am just being pedantic. I can't think of a better way to express it. So perhaps it is fine. Read through yourself just to check - and then I trust your judgement.Everything else is fine. I sent the pic of me on Slack. Thanks for the great collaboration.
|  | ||
|
|
||
| And just a few months later, we had built and released TechDocs, Spotify’s docs-like-code solution for internal technical documentation. And a few months after that, we had the curve that I had longed for. Nice gradient, eh? | ||
|
|
There was a problem hiding this comment.
Added the "for internal documentation." qualifier here.
| So that’s about it. There’s your long-term relationship advice. Not bad for a bunch of techies eh? | ||
|
|
||
| One last note to let you know that **we have now open sourced TechDocs**. Let’s take TechDocs to the next level together. Everything you need to know, you’ll find in the blog post [Announcing TechDocs: Spotify’s docs-like-code plugin for Backstage](https://backstage.io/blog/2020/09/08/announcing-tech-docs). | ||
|
|
There was a problem hiding this comment.
I like how this is written so I left it, and added the ### Resources header and section - see what you think. Hopefully the "Tools for TechDocs" is an accurate description of the techdocs-cli and techdocs-container packages repos.
|
|
||
| gary_niemen: | ||
| name: Gary Niemen | ||
| picture: https://docslikecode.com/images/gary-niemen.png |
There was a problem hiding this comment.
I pulled this image from your GitHub avatar - it won't show in the preview but will appear once published to the live site.
| tags: [cicd, backstage, spotify, github, git, portal, internal, documentation, developer, docs] | ||
| image: | ||
| path: /images/spotify/soundboard-han.ailes.jpg | ||
| caption: "[Flickr han.ailes](https://flic.kr/p/oVPTVm)" |
There was a problem hiding this comment.
You can click https://flic.kr/p/oVPTVm to see the image... it reminded me of "backstage" and music which matches my great experience with Spotify, I'm a big fan of the service. :)
3 participants
@garyniemen - I made a few edits and I'll indicate those inline in this PR. Once it builds we can take a look at how it renders as well and see if you like the header image. Thanks so much for this article!
Here's the preview: https://5fa61d947f1bfd000789f41f--docs-like-code.netlify.app/articles/ten-tips-maintaining-long-term-docs-like-code/