Ad Clicks : Ad Views : Ad Clicks : Ad Views : Ad Clicks : Ad Views :

Here you will find everything about smart and technology

EuRuKo 2019 – How We’re Making Tech Documentation Better, Easier, And Less Boring by Bilawal Hameed


>> Cool, how's everyone doing today? Good? Yeah Having to start before a break is always a dangerous territory but I'll try my best

It's been a while since I've given a talk but yeah, I'm excited Thank you for having me I work a lot with documentation, also as a Developer Advocate, so documentation is kind of at the heart of everything I do My name is Bil, I live in Oslo I'm originally from Manchester England, although my accent is kind of messed up these days and I currently live in Stockholm, Sweden

Has anybody been to Sweden? Then you know how utopia of a country it is It is really interesting I used to work a lot with Rails which is one of the reasons I'm here So I want to talk you a little bit about what this talk is First of all it's a new talk

It's the first time I've given it, it's been a while as I mentioned that I've given a talk so bear with me I'll try and put in some Ruby-related stuff, as well, but it's very much general around developer experience and also, yeah, not super-specific to Ruby So if you work with other languages, etc, this should be applicable to you, as well And lastly it's an opportunity to knowledge share and I think that's that's a main reason a lot of people are here

I'm going to start off with the problems Some inspiration that we've kind of had and maybe things that we could have used to help us improve our documentation culture at Spotify, the approach we ended up taking, the impact we had or we're having And then some takeaways, something that hopefully you should be able to remember If you remember something, then that to me is a success So I'll start off with the problems

So documentation isn't exactly a new problem Before we used to have books for a piece of software, now we probably have just a ReadMe But it's not a new field Isn't it supposed to be easy to create If we think about all these different tools that we create for Rubyists, we have Jekyll, as well

the other tools are very much around documentation, but isn't that supposed to make it easier? If you look in the world of TypeScript, as well, you have tools like tsdoc, it generates reference documentation for you automatically so you don't even have to write any comments or any sort of documentation, no copy and pasting it Just does it for you Isn't it easier than ever supposed to be to publish documentation, as well? I mean if we look in the Ruby world again, we have Rubydoc, how many people have done this with our projects? Not so many anymore But this used to be very popular And of course we have the whole world of tools, as well

But these are very much designed around static websites, but we just use them for documentation, as well Which isn't a bad thing, but it's what we do today And these address many of the public needs, the needs to brand your projects, the needs to like have fully fledged websites that explain not just how your system works or how you get started using your system But they don't address many internal needs And what I mean by this is things like ownership, things like what's the history behind this project

These are the kind of things that you don't really expect so much on an open source project, maybe on the big ones like React and Rails, etc, but I would consider them a small percentage of the open source projects we depend on, so they don't always address all needs And the reasons you do open source documentation is different to the reasons you do it internal Internal it's your job and you're paid to do it, but open source you have a invested interest because you can choose what you want, right?We have many different places to do documentation at Spotify One of them is GitHub pages

I mean people generally internally don't want documentation websites If you're building software internally, you want to provide documentation, but you don't want to build a whole site around it Whereas externally I would love to do that It's pretty easy So I think that the idea is like they want to have documentation, and then when they open source this project, then they'll have a whole website and a bit more around it

And I think the only people internally that might do this is infrastructure teams where they do need to sell their infrastructure internally, but for everyone else, it's really not an interest for them, so they don't use GitHub pages so in the end we have a small percentage of software at Spotify that actually uses GitHub pages I think I can count about four that we still use today of the many systems we have But then you can talk about GitHub in general, right? You have ReadMes, you have wikis, you can use all of that But some documentation is so outdated That's not really helpful today

We've deprecated, we've long gone, but still it's there so we end up having lots of content but it's not actually helpful And I think that's a problem that is slowing us down as a company Next is confluence, which I again for many technical people it's clearly a no-brainer It's not really a solution for technical documentation, but for many companies they're actually doing this, we've already spoken to companies and they're like, confluence is for us And to me, that doesn't work for developers, it sounds so obvious, but it's not

So I wanted to clarify that And then the next one is like generally speaking when it comes to a company like Spotify when things do move very fast and I'm sure many of you here have a similar culture in your companies, it's very hard to get the work prioritized It's very much like, build the code In the past we wouldn't even have tests but then we're like, OK, let's add tests, let's make sure everything is great But documentation will be the last and you'll very much have the mentality that let's do documentation later, or at least that's what we have

And it's just not working for us, and we end up being in this position where people have to know an entire codebase to be able to contribute and that's slowing us down a lot And just to give you an idea, like Spotify, kind of everyone refers to us as like the company that's nailed agile, but — I mean in some ways, yes, but for us, internally, we had many different roles in the team Many of us are cross-functional If you look at this, which is Spotify in the early days, engineer, QA, tech writer and DevOps Not everybody would have a tech writer, but let's assume they do

DevOps has kind of been done away with Kubernetes and Google Cloud engine So you don't need DevOps really in a team anymore Engineers just need to learn a bit more to configure those Same with QA Engineers would write stuff in the past and go, well, my job is to write stuff and not really guarantee it works

And then QA would come in That's not really a thing anymore So now engineers are required to write documentation — write tests I think a lot about documentation And then tech writer, as well, which is responsible for making sure that people know how to use your system, people are using it in the way it's intended to

Even that's slowly moving out, but still, I think it's the last thing in these four that's moving So in the end we end up having teams full of more engineers and less of the other roles so we end up becoming less cross-functional and I end up making engineers more T-shaped And that's where Spotify is going more and I'm sure other companies are, as well Engineers have more responsibility, but there should be more engineers But we end up with a future where there aren't enough engineers, but let's go back to 2019, let's keep it simple

But there's a lot of issues The first one is too high of a barrier, so a lot of engineers find it difficult, surprisingly to write good documentation Despite the fact that we read it all the time, we don't know what good documentation looks like for our code For me, I've been writing documentation for so long, I have a different view on this But this is what we've been seeing from engineers

Second thing is undiscoverable We take that granted we copy and paste it from Google And if we think about the first two as — the first one being creating documentation, the second one around consuming it, the third one has to be maintaining it and one thing we've seen is we define it as trust, right? If you're reading documentation, how much do you trust it? Does it answer the problem you're having? Is it going to take more time away from you? And all of these three things end up with a poor and slow developer experience and to me I don't like this I like engineers to be more fast, more efficient and just have less frustrations, really In general Spotify is trying to make engineers more effective is the right word

More productive means more hours so we don't want that But we wanted to be more effective so we kind of pitched the idea to try to solve this And bring out some good engineers to solve this, as well as tech writers and we've been doing it for six months and want to share our learnings and if you're doing anything in your company, we can learn from you, as well When we were thinking about this 6 months ago, we were talking about can't we just use another tool? We don't really like writing software The more product aspect of my mind thinks that's the last solution

I mean the first one is obviously why don't we just enhance our use of GitHub, right and make this better, maybe with better tooling, using the APIs, etc, and this is something we battled a lot against, because GitHub is a great tool and the one thing it does really well that we ended up taking out of it was that if you look at the ReadMe, it's always close to the code, right and this is how I think about tests If your tests were in a different repository to your code, you would probably almost never update your tests, or would be a lot less likely The same thing applies with documentation, some people have documentation in a separate repo in I don't know, Slack notes or Google docs or somewhere else But I think having it close to the code I think is pretty great

So that's something that we took from it, but the reason we didn't end up using it is we just weren't able to experiment enough with it For example, we wanted to solve the idea of trust and maintainability and that was the one area where we would struggle to find here But that being said I still think we could end up moving back to GitHub This isn't like, oh, GitHub will never solve our needs Just for now, really

The next one is About Library It's an open source project What it does is takes Google docs and you put them in a shared folder, and you can just search for it It kind of just categorizes it automatically This isn't really helpful for technical or rather API documentation but if you think about RFCs and these sorts of things are very popular in companies and rightfully so

The one caveat with this is that documentation not close to the code Should RFCs be close to the code, should they be closer to yeah, the projects that you're working with or what it's related to? Next is a tool called ReadMe, and many people use this, many teams use this, but this is very much designed for an outwards-facing product team Like I used to work on developer Spotify at comm and this is a perfect candidate for it and we kind of collect all the documentation internally at Spotify and we're that one team Internally there is no one team every team has their software, has the documentation, so this didn't really solve our needs, either

And I wanted to bring up this quote and I think it's so true: Documentation is a love letter to your future self, but I want to like amend this quote and say that good documentation is a love letter to yourself, bad documentation is a hate letter to your future self So with that, what is Spotify's approach to this problem We're not trying to be necessarily radical We just want to solve the problem Has anyone heard of Docs Like Code? Not necessarily having docs that are code, very much making it part of the developer workflow and I when we edit code related to t we'll probably edit the documentation, as well, and this is a cultural thing that will happen or it's something that we're trying to push out, as well and Google gave a great talk about this and how they've been adopting this policy

And it's working very well for them So it with that it kind of inspired us to build on this idea and then we ended up building this tool, it's called TechDocs — very unoriginal name, technical documentation, TechDocs — but we had to think of a name fast We basically have this tool where documentation lives inside of T/docs/the project name and we open — we haven't built this whole thing The other aspect which you may see here is this right hand bar or the box I haven't given it an official name

Any suggestions would be welcome It's very integrated with Spotify's software ecosystem It's very related to Git, GitHub, who are the people you can contact related to support, which team owns it, when was it last updated and we want to evolve this kind of experience to get people to like see this very much how you see code If you think about git blame and all of these different work rules, as well But why even do this? Why not just — how is it worth the effort to even try this? Well, I mean in reality we mostly didn't

We used internal docs, Google Cloud, Kubernetes and we built this whole thing in a week and we were basically spending all our time with data, rather than actually with web But it's still very interesting and there's a lot of web-related aspects to this I mean this is very much a high-level view of how the system works I mean when you're writing your docs folder with your mark-down, you just put your code normally and on an internal CI platform, check, and then it uploads it to Google storage And we basically read out from that and we add some injection, and we've optimized this so engineers can actually access our Google Cloud Storage bucket without the need of a proxy, so every engineer at Spotify has access to our GCS bucket and they can read the documentation right off the bat so we're almost abstracting as a way the need for a proxy

But we're trying it out to see how that works Especially for engineers and data scientists, etc So we want to evolve and experimentation, we want to make it very informative We want engineers and people to know how, within seconds if this will solve your problem Especially in a company like Spotify where this changes daily

And here's a little bit about how we thought about it and how we are thinking about it I mean if we think about it in these two areas, standards being more of a cultural thing, like how do we make engineers think about documentation as code? And then the workflow, which is a mixture of tooling and integrations and those kind of things And the problems I mentioned earlier about too high of a bear ye, undiscoverable and untrustworthy, how can we use workflow to solve these problems Hopefully that's not too confusing Let's break that down a little bit, actually

So with standards, using that to solve too high of a barrier, we introduced this idea of two documentation types at Spotify Code which is not a new type It's very much how you use it today, you have a docs folder and you have code But system documentation is a fairly new thing and something that we realize not many other companies do and just to give you a quick explanation of how this works, we have our web API Each part of the web API split out into its own service

We have web API tracks, albums and many more They have a docs folder and that describes that particular system, but we have nothing that describes all of web API General things like authentication, all of those things and that's where we have the idea of system documentation where this is a GitHub repository, just has a docs folder, no code, could do in the future and it operates as a system doc or system documentation and this works very well for us and a lot of people are using this and then we can use how they're linking out to these other ones to build up a graph of how documentation lives at Spotify and using standards, as well, to solve discoverability This is simple You'll be surprised how many people don't do this If you mention GCS or API in your code This link to read more about it Having references to the concept you use in your code is pretty critical, because otherwise you're asking engineers to Google more, rather than just like taking them straight to the answer, and that makes people slower

Even more so if they don't if find what they're looking for And the next one, sorry, the next one is documenting error messages, so this is like a very good example So many times that we have error codes, and they don't explain what it is that we are — what it means So having these documented is pretty great And the next one is — suits the command F workflow, so so many developers look at documentation and the first thing they do is command-F because they want an instant answer and we don't allow research around this

Because don't make documentation too small Make them not too big, either Guiding people that way with standards, as well, and here's a very applicable example with Sorbet This is great So just a good example there

Using standards to solve untrustworthiness If you think about Imposter Syndrome, documentation is part of the answer at least to solve this Making it easier for people to self-serve and being able to work with your code without having to ask people That's a really important part of it for us The second is documentation is a part of tech health

It's something that we should think about when we think about systems that are hard to maintain, it's because we don't understand them, because documentation isn't good So I've only got a few minutes so I'll kind of rush through these We provide tooling for skeleton documentation This is not anything new or radical You have this, as well, externally

Preview documentation, if I go back to tech docs and code, this is applicable to that Continuous documentation To me the idea of continuous integration, continuous deployment is the master branch is reflective of reality And I think if we think about that in documentation, we'll always having a continuous documentation mind set is — and this is as simple as just giving that impression that it is continuous Friendly to power users

Internally we have this domain hack, I guess, you type in docs and it takes you straight to our documentation and you can type in question mark We hijack the query params, and they can do that instantly If you want to find out specifically for architecture, you can type in docs/architecture and you can find the mySQL, as well GitHub workflow integration It if we think about opening issues and PRs to make changes to documentation, not everyone uses gi its had you been issues, though, people use Jira, so instead of the idea of creating an I shall we're about where people can create suggestions and changes

Shifting to a culture that everyone at Spotify can benefit from this And this is how it works internally We want to change and make that work for pull requests, instead Workflow to solve discoverability, there's only two here, but one is we use Cloud Search This is a new tool that we started using

This is simple it's making sure that the culture that we have like googling things, we want to bring that in internally, as well We have this tech docs internally and we want to basically give that culture and this is our of doing that Next is predictable URLs, which is pretty straightforward And then last part to this is solving trustworthiness And this is the more interesting approach that we're trying out and we're using a lot of data and we're trying to gather data to calculate documentation trust

If documentation belongs to the code, we can see how often are you updating the documentation, how often are you responding to feedback? How can we build this to build documental metrics that say OK, the documentation is good, at 60%, because right now engineers don't have an idea how good or bad their documentation is They can have an instinct, but that's all it is So this is how we do that if you're calculating trust, come up with issues, and raise them, and bring the right issues, and this is a really complex problem if you think about it, because content is text and if we think about the talk yesterday, it's not easy to decipher it always So very quickly, what impact have we made? We have 6 people on our team, we're very cross-functional I think about half of Spotify is using this already, which is a pretty big deal, we have many thousands of engineers

And one metric we're using are page views People find this valuable People keep navigating around documentation And how often are we using that? We want to build these metrics out and this is an interesting quote I wanted to quickly highlight is a team was moving to tech docs and they realized a lot more people are contributing and using it because they know how GitHub works, with Jira, they might think it's foreign

This is one of the most important things at Spotify, moving forward, at least And this is kind of a growth curve of how documentation has shifted at Spotify It's slow Barrier of entry is higher People have to move from Google docs, it's not like signing up for Spotify where you get it straight away and you're considered a metric

So what are some three takeaways We want people who be able to self-serve to be able to operate independently and then when they feel confident to be able to ask a question that they know might not sound like a stupid question, they have the tools to do that Of course we don't have this culture of — there's no bad question, but still, people feel that way So we want to make it easier for them Second easier to prioritize

This will build a culture where we can move faster and then lastly making it less boring for engineers by tying it into their workflow, not giving them new tools to learn, just something that works for them already Cool, and that's my talk, and thank you so much for listening [applause]

Source: Youtube

This div height required for enabling the sticky sidebar