 Good afternoon everyone. So as we realized in the keynote this morning the community at large is producing some amazing open-source projects We've got new innovations constantly happening new projects constantly updated hitting their 1.0 releases And it is awesome. Everything is awesome But also on the flip side of this from a user's point of view it can feel overwhelming it can feel a lot of information being thrown at us constantly and And this is why it's super important that all of these projects and open source in general has awesome Documentation and that is what I'm hoping to share with you today about how Documentation can transform a project and make it easy for people to get started and have an impact on how that adoption can help And so my name is Ben Hall I am the founder of catacoda catacoda is an interactive learning platform for software developers and so Directly in the browser you get given an interactive environment which have been pre-configured With all the various tooling so docker kubernetes open-shift and alongside that to guide you you get a step-by-step Tutorial and so you can learn and follow along and solve real-world problems and you may see in us on The red hat stand downstairs, which are using catacoda and the kubernetes website Have catacoda embedded in order to help bootstrap and kickstart people's experience and as I said the aim of the talk is to discuss and share some of the experiences which I've had in some of my Kind of viewpoints on how documentation control Can transform a project and how it can go through and make a user's adoption easier and I think what your projects more successful And while my focus will be on open source. We are cloud native con The same patterns and the same approaches apply whether it's an internal API for your internal dev teams Whether it's a commercial product or whether it's a side project which working on and hopefully will turn into a lot to think at the end of the day all of these techniques can be applied in exactly the same way and So documentation is a huge area and so it can be very difficult to understand where to begin and what to focus on and where to spend your efforts and so Sam Newman who's Awesome leader within the Microsoft service community did a very timely tweet and very recently and then to hear his Viewpoint and his definition is that while creating Rethoughts and creating projects is amazing is our responsibility of creators to also give guidance and give explanations about how those projects should be Implemented it's important that we're not just producing the toolings But we're also making sure that people are getting the best experience are getting the appropriate experience We're not just sending people down a blind path and misleading Configurations which will end up hurting them later on and this is that documentation can help ensure that people are getting this great Experience based on how we the creator think the tooling should be used And the problem with documentation at least within a development and technical sector is a lot of time We assume that people just be able to read the code and understand exactly what the code is doing And then as such how it should be implemented and this was another great timely tweet where Historically a lot of the initial documentation was just read the tests or just read the code and understand what it was doing And how it works and this is a fundamental barrier for people to start implement projects and getting started If they have to understand what the code is doing They said that birdings if your code is not correctly created So then have to write It could be a different format and it can really make a barrier for people going and with so many different projects and so Many different implementations It's also very easy for people just to go to the next project or just close the tab and just move on to something else And the general vibe and I like a lot of the documentation which we saw can be thumbed up by this awesome diagram Which I'm sure many of us have seen but the premise being that we expect people to simply install X technology and then be able to successfully run it in production at scale as if we were Google and the reality is we need We need to have We need to have much clearer guidance We need to help people get from being able to install it to up to running at full scale And so instead of expecting people just to jump straight in our documentation and our approach needs to be building on expertise We need to give the right information at the right time to make people successful and not Overround on with complexity with confusing information with too much technical information too soon Because this will just be confusing and demotivating when it doesn't make sense or the user can't understand And so instead by providing information in a piecemeal way and building up that knowledge We can get them to the end goal We can get into that great experience of how the product works and how the product operates without completely overwhelming them And then our experience the documentation begins long before where most people focus on most people focus on creating developer Portals and make sure that the reference API documentation is perfect But the reality is documentation starts way before that and it starts and it's attached much more closely to the user experience And so if you spend time taking a step back and looking at how users actually adopt products And adopt new toolings and new ideas. There's five key stages. They'll go for an exploration like this is a new awesome technology What did it do? Like what problem is it solving and then they'll try and use it They'll experiment see how it works how to get started If it does actually throw problems what problem to this solve and then eventually get up to the point where they need reference and they need That expertise and these five stages map very cleanly Until what an emotional journey looks like from a user's point of view that how People will actually engage with projects. So there's a technology trigger. I a new project was just announced on Twitter or a key note Like this morning announcing something like core DNS. It's like everyone's super excited It's like I had this could be the answer to all of my dreams And so instantly they'll get this expectations and it will be probably a little bit over eggs Compared to reality and so when they try and use technologies and trying to implement it They'll start getting disillusioned. It'll be too much trouble. The cold samples will be broken The examples aren't detailed enough and so start getting disillusioned And it's not the answer to the dreams and they'll potentially move to something else and try a different product technology But if users can get beyond that then I'll start to see the gold I'll start to see where the project sits and I'll start being productive and this is the aim And this is where we want to make sure that people going to within our documentation journey And so these five stages map very cleanly onto this kind of emotional curve Use of that having to and so when we're thinking about the types of documentation which we want To produce and how we want that documentation to work We want to be making sure that we're providing the right information which maps this journey about how people are experiencing and learning more about the technology itself And so I just want to start by going into some more of these stages in more details So let's start with the X for the exploration and Fundamentally at this point users like why should I care like why is this project important to me and at this point? They're confused they may have seen a tweet 140 characters didn't go into much detail or it may have been mentioned in a talk and it's like okay I'll look at that later and so they need some more information and watch Technology is a great It can be confusing when people land on new websites So this is an example of Docker while Docker has completely transformed our technology industry and did some amazing work When you go into that home page the third thing is discussing is Kubernetes and From a user committing blind to the container ecosystem. This is somewhat confusing Not only do they not know what Docker is but also now being introduced to the concept of Kubernetes Which is more things they have to understand and as you know the guy for for more of Kubernetes For more of the Docker website they introduced case to it is which is great But again, it's not really explaining what containers and what Docker are and then they'll drop people into the like the far end Like how do you contribute back to Docker but contribute as something called Moby like what's Moby? What is Docker and so this journey can become extremely confusing from a user's point of view and again This is why I think documentation starts really early on in the journey because this is all forming into users Perception about how the project works and how they can start adopting it and using it and so if you look at some other projects which I Think a really good strong examples Kubernetes so it's very clear instantly what the purpose of Kubernetes is its production grade container orchestration And so instantly you know whether this is something which you're interested in or something Which is not for you and you can move on and the same as you're going through it It's a very clear tagline. It's got some good explanations and then it's telling you there's where to go next. I in this case Try the interactive tutorials. So you didn't know where they're expected to go and how that journey is expected to flow They're similar with Project Calico and Tidic Gira. It's very clear what that project is there What's the purpose of why it exists and again for news and either how to get started or where they can go for a demo More information then with terraform again great examples so clear tagline So it's just a flap strap lines and giving people the pointers in a very clean direct way Until when people are motivating or excited and no one to explore more They know instantly whether it's relevant for them and then where to go next and this is something which we're trying Should be aiming for and even complex things like Google still manage to have key Twitch points like using Google core infrastructure machine learning and using all of the great buzzwords to get people excited But still telling people how to go and where to go next and so once we get people over this initial barrier Like this is a project, which I should be paying attention to we want them to get started as quickly as possible And what we want to demonstrate is answering the question I do actually solve my problem if we're looking at something like Calico is like called secure networking Okay, is that the problem or is that the answer to my secure networking problems or is there another? Vendor which I should be looking at and there's many barriers which people pin away in order to make this What should be a very awesome exciting experience for the user somewhat problematic and having lots of barriers in the way And the one which I personally enjoy is here download this 10 gigabyte virtual machine image In order to have a demo of how my product works and like This is fraud with danger if you'll think that you're in somewhere like Australia 10 gigabytes is a significant amount of data to download Even in central London 10 gigabytes will still take you an hour to download and then it's a VM So how do you run that like are you gonna start introducing and teach people about vagrant teaching people about hyper V KVM like how does that work? And so there's all of these other questions that the user is going to be Engaged with when they just want to simply figure out whether your product is what they need Or not and to help them get started What we see more of more frequently is deploy using cloud formation or deploy using Azure or Google Again now you have to start explaining how to use cloud formation or how to use particular cloud vendor And at the same time hoping that users forget Remember to turn off the machines at the end of it and they don't get this unexpected invoice for $300 When they all they wanted to do would figure out whether they wanted to use a product or not in a third place And so these types asking for people for a huge amount of commitment Up for and before they've actually even proven or been shown whether the problem is right for them or not And so there's a few techniques which we find beneficial when we're Training people and getting people started and that helped with their adoption and how people understand what a product offers With Kubernetes and what we're doing with the Kubernetes team We've got the catechoda interactive test drive and so people can start Kubernetes. I start Kubernetes cluster in the browser They don't have to download anything. They don't have to install anything They can start deploying containers and just experience what it looks like and how it works and how it operates We see it with other Kubernetes projects as well. So the people from hipto and we have cosnet and so you've got the jason net code Defining a Kubernetes cluster and then live in your browser You can tweak it and edit it and see instantly to transform Jamel and so you can start putting together and exploring How this new approach works and whether it's like for you and whether it's something which you're interested in and for me This is all part getting people excited and motivated and understanding where the product sits Which is the whole purpose of documentation? Another great example is stripe So stripe is a payment gateway very API developer driven And so the first thing you get an experience when you go into that documentation site is a code snippet And then it walks you through and gives you information So tell you what you expected and what's going to be required of you when you're implementing the API But it would then also give you kill commands And so you can execute these kill commands locally and actually experience and interact with the live API And so this was in in this case create a customer and you'll see that customer created on the journey And then you can go through and simulate creating card payments at the end With everything successful within five steps. You've gone through the entire stripe API integration journey You've made live API calls and then it tells you where to go next Like how can you continue being successful? How can continue pushing forward and keeping that motivation and that energy about learning this technology alive? And so it's a really nice example of well, how you can demonstrate API in a nice clear way On the flip side, it does also still introduce barriers like it's got dependency and curl Like what if I don't have curl available? What if I'm on my iPad or if I'm on my mobile? I still want to be able to go through that great journey and take the documentation But I now have the dependency in this blocker And so as you introduce in these different elements, it's important to think about the context About where the user is at that time and what the user will be doing. Yes Most people will have curl but it's something else which they need to consider And so there could be alternative ways to solve that problem in a much simpler experience from the user's point of view But the premise and what we're trying to get to at the end of this kind of initial getting started stage I initial five minutes where people are trying to learn and experiment is you want to showcase what your product is offering Showcase what it can do and kind of allow users to experience that and allow them to prove for themselves That this is something which is worth and continuing and worth exploring some more And this gets it on to the point of kind of the onboarding So now we start getting into it into the more of the traditional longer form Documentations and this point of the user like they've been shown what it does and so now Historically they want to explore more They want to start using the product interacting with it and they need some support and documentation in order to be able to do that successfully and Ironically in my experience the best documentation is a documentation which we don't have to write if we don't need to write Longer explanations on detailed blog posts or longer detailed guides to help people then or the better and Fundamentally that's because people just don't really read on the internet like historically We're always skin reading were always glancing with distracted We've got multiple different tabs open And so it's very hard for people to concentrate and read and digest these long-winded Very detailed long-form documentation guides And so there's different ways that we can break that up and we're very fortunate By writing technical documentation about the tips and tricks that we can use Obviously code snippets are a great example Developers that will stop and read and digest the code snippet much more easily than a paragraph of explanation Defining how to implement something One thing which we or which I personally get really frustrated by it have completed code snippets So with this is a great example. It's very clear that we would find it's got even some nice comments But if I took that and tried to ruin it in a golang rebel it wouldn't work because it doesn't include the additional functions the import statements all of the additional information No, it's one needs in order to be able to experience to its full extent and so it's important to kind of think about how you can Include all of this noise and it's additional information without overloading you that without it being too complex And so what we're seeing a trend of is people having buttons or show hide toggle and so that when you have Your code snippet, but before it's all hidden and it doesn't have the additional Import statements doesn't have these initial function definitions, etc But if the user wants to go ahead and execute that they can very quickly just discover it with a button And I have that information there and so they don't have to go off and discover and look around For additional bits of information. So this we think is a really nice technique We're also seeing more and more integrations with API's to Spotify redevelop in their developer portal and for now it was part of that documentation they're getting people to authenticate and gain an access token Once they've gone through and as authorized and they've got the access token They then update automatically all of the code snippets Which uses that live real person's personalized access token And so when users are going through the copy and pasting trying to execute the code They don't have errors. They don't have weirds and things which don't work They get great experience out the box and without having to change anything And so as we're building these documentation needs code snippets Sometimes we hit problems and we hit errors where it's actually just very difficult to explain and it's very difficult to describe accurately how something works and We've had I'm sure many of its experiences with doing things like installing Kubernetes Kubernetes is somewhat of a complex thing to get set up and getting thought Hence why we have awesome tooling like tectonic and OpenShift and all of the Google managed services But also it's an highlight that there was a problem There was a missing gap within the workflow that developers are experiencing about how they're going around and how they're getting Kubernetes set up And so a great example is work with the team of doing around kubaddle where instead of writing these long-form Explanations and documentation about how you get it set up that you have built at all which will do it for them And so instead of trying to document the missing UX experience They've wrote and they've automated that for people to get started with and so now as people are experiencing it And as people are going through it's more of a self-documenting clear definition about how users can get started They can go in they can talk to kubaddle minute and now do all of the leg work and all of the hard work for the developer Which also means we don't have to document all of the hard work which is happening underneath So once people got Started they started to experience the product. They understand and motivated. They want to learn more We get into a stage of guidance and discovery and so this is now where people have Ideally solved a problem or they identified that this is potential solution and they're now exploring and looking out What are the problems can be solved? What is a document? What are the problems? Did that solution offer and this is where you start getting the more traditional long-form documentation which is very focused on Particular problem spaces and I get can get very niche And this is also a great opportunity to start promoting and highlighting things Which are happening within your community writing documentation solely from a team is hard work It's time-consuming it takes a long time to produce very good detailed documentation And also it can be hard to discover all the documentation which is required And so what people like digital ocean are doing is leaning on that community and Promoting all of the awesome work all of the awesome ideas that the community has and then showcasing that part of their Documentation and this then videos how people can get started And so when you search and think like how do I win for me for years and a bootie The chances are that you'll land on digital ocean because that's got the best documentation in Google and as such it's ranked more highly and they respect the community and they respect the contributions and so now there's over 17,000 different tutorials created and digital ocean will Compensate people when new tutorials are accepted and added in to the catalogue because they respect that community effort So it's a really nice way to start reaching along more the long tail Documentation and long tail of guidance and discovery that people may be looking for because the community has probably been and in that already and a really great way to foster this and help is by having things like writers guides and Defining what's expected from a contributor. How do people get started? How can people start writing and sharing content with the product and with the company? And so this is a really nice way and we're seeing this with some of the work that red hat team are doing with the portal and so As part of the 11th Angeles works all of this is on github It's all very open and it creates that learning pathway about how users can go ahead and experience Open shift and what different problems that can solve In an interactive way and so as part of this because people don't read on the internet and because people can't Focus on long form text everything's broken down into the step-by-step processes and more of a bullet point Very clear headings very clear signals about what's the users expected and how they can actually go ahead and solve different problems And as you start and build in these awesome documentation websites It can lead to a problem about discovery and how do people find where other valuable content is So something which I was super impressed with is from Twilio And so when you go into their docs website, I ask you two questions What's your coding language and what product are you interested in learning more about so you can go through you can select no JS and then select them like SMS or phone calls or Roy 35p and then it will take you to the appropriate getting started guide and so instead of going through huge amounts of links and indexes about where documentation is Instead users can just jump straight into the game started for the product and for the problem in their language and in their context Well, they're familiar with and so it's a really nice workflow about how you can Have lots of different content and make it very easy for people to find in a very easy way Another approach which Google I've done is having a single page which then has examples in all of the different languages so in this case this is their big query API and Instead of having different pages. So I paid for PHP SDK paid for go paid for C sharp They've got a central point where people can navigate to and discover the required documentation And then they can flip between the different examples based on what their language is and so it makes it really easy for people to get Started and see the differences between different languages that they may be implemented in their technology And once we start getting to this point we start getting to the traditional reference type material I how can I start becoming an expert with this product? And this is generally the documentation which we generally start writing service is the one which is focused more on the long tail It defines all of the different API Events different API calls and we can use templates such as one from stripe and read the docs in order to highlight and showcase that But we also want to see about how we can make that further make that Learning experience More interesting from a user's point of view and so instead of it being locks of blocks and traditional ways of documenting methods companies again using Spotify an example make it more interactive and so they helping people explore and Understand what's being offered by the API in an interactive way by having an API console And so people can use real data or they can fill in some sample data Automatically and start interacting and exploring the API that they're trying to get more information about and then obviously under the covers they've got the longer form traditional guide if people do want to know what all of the API calls are All of the API calls are and the methods which are possible and so that for me is how are you the journey maps from them getting familiar with the product and kind of Becoming familiar and then get into the stage of where different types of documentation fit into the users different mind sets But what about read miss like get hoping now a huge source of information and a huge central place Where people go to explore and discover what's possible and so the read me it now Equally as important as I use it a product home page for example And for me the read me thought about signposting It's about giving people just a little information that they can be productive and they know where to go and where to find out more Information and it's really important because the read me sets the tone for the entire project It sets to tone about what is considered important how much effort has gone into the project in some cases and whether it's being maintained or not and it kind of Give you that initial instant experience about whether this is something which you're gonna build confidence and trust and build on top Of or it's something which you may Not have so much faith in and so again if you use coup d'adam coup d'adam as an example It's got some great signposts. It's got information about where to go for support and how to get started It's got something with information about roadmaps, etc But it doesn't really tell you how to install it. It doesn't tell you where to get started how to Push forward and so because it's open source. So the pull request pending which I will submit but generally in my On his opinion This is what I kind of look for when I go into an open source project These are the kind of two points which I'm generally interested in understanding more about to obviously what are the goals of a project Why does that project exist in the first place? Why do someone invest time and effort in creating it because that's an important thing for people to or for me to understand And then like how do I install it? How do I get started do I need a package manager? What kind of API to the do they require etc? and then starting to get productive and actually use it and because it's very open source and we want to encourage that community Giving people an indication of the status, right? Is this very an actively developed on or has it been putting to maintenance node and we're no longer pushing forward with it And then of course things like contributed to guidelines called a conduct So we're building a good strong solid open source project and then the license to make sure that everyone is happy And so a really good example of this is mini cube. It's a great explanation at the top about why mini cube exists And how or what problems it's over in it tells every people there clearly given an operating system This is how you install it and then it moves on to a quick start guide So it tells people right when she's got mini cube installed This is how you start deploying parts creating clusters, etc. And then finally some rise with Hints about how you can get more information push it into advanced segments contributed to guidelines and a community as well and so it's really nicely formed at any point no matter how Experienced you are or inexperienced you are when you go into mini cube It has all of the information which you need in order to be productive and make sure that you're making the right decision It's a really good technique which I think are sometimes overlooked when you're thinking about read me is that you have the ability to Include images which are always great, but you can also include gifts for this is an example of a gift which will Deploy open shift and then start deploying pods and start deploying services So again, it's a nice way for people to get an understanding of where that project fits in a nice interactive way But we also don't want to start overloading and put too much information into the read me because that can make no noise And more confusions and so we can use a details element to start hiding links and hide in examples behind a drop-down And so instead of having all of these examples and next steps Within the main line text they can be hidden And so if you did want to find it and they want to know more then they can But by default we're not overloading them with too much information And because we're on github it's important that we start thinking about how we can foster and how we can find Encouraging a community and so by having the docs in a separate website or a separate repository Makes a great play for people to know and understand how to start contributing They know exactly where they need to go and it's not being it doesn't have the noise and The other conversations happening around the actual core project and so docker is a really good example as is the kubernetes website and the Documentation so people know and it can start to contribute contributing They can start raising issues and improvements and if they want to without getting the rest of the noise about what's happening in the proposal And it also starts you having more focused communities things like the special interest group around the documentation and The doc sprint which happened yesterday is a great example of how with this focus energy in the focus community You can start pushing dogs forward in a much more interesting passionate way And finally what we want to do is start making it easy for people to give back and give feedback and share if they notice a Typo if they notice a stake making sure that they can actually highlight that to the team Making sure that that can be improved for everyone else in the community And so within kubernetes documentation every page has an edit button Which takes you to the relevant part in the github repo and so that people can start easily making changes and making suggestions about how it can work The one issue I do have with this is we need to start thinking about like how does that work from a user? Who doesn't understand get or doesn't understand github and like introducing concepts of pull requests and forks and There's Aspects can be too overwhelming especially when you just want to say like it should be a small typo needs to be fixed And so instead of people pushing people to walk down a path of fork in a repo making change directly What we've started doing with our dogs are people pushing and encouraging more people to submit issues and just highlighting the fact and then one of the community team members can go ahead and Make the fix directly and we don't have to worry about contributing guidelines or a good light into agreements, etc And so these are some of the tips which we've experienced in which we find personally valuable and what we have found valuable when we've Been promoting products and encouraging other users to get started and all of these new shiny technologies But our common question is who creates the best documentation like we've seen lots of different examples of things which I like and things which I find Beneficial and what users find beneficial But who does the best and it is a hard question because every documentation is different and every project has different objectives, but an interesting one is When you start looking around the community and start seeing what the people's recommendations are And so there's an awesome blog post by Cristiano better in London about the developer experience lessons from Lego and this is not something would you generally look at as a source of inspiration for technical documentation But Lego is the perfect example of what awesome documentation looks like it's very simple and straightforward about what you're trying to achieve From the outset I you're building a car or you're building a plane It doesn't tell people to start from just hit one leg of brick and there's the end result Instead it's building up people's confidence is showing all the different stages at the right point at the right detail About how people can be successful and so instead of overloading them with information It's just providing just enough that they can make the next step and the next leap forward And it's also very good at promoting the community It's very good at fostering new ideas And so instead of a particular Lego set you would like to see you can go on and you can submit an idea And if it gets enough salt then Lego will produce it and Lego will actually create a Lego set in this case around red drawer and because it's been Design in this way it Allows people to be very creative It gives people enough support and enough ideas that they can build whatever they want, which is a whole purpose of people using login in third place and if step-by-step nature has allowed people to get to the point where they can do all some things that build build elephants or build entire Parts of America and so I think that's a great example of what we can look for When we think about the documentation and think about what we need to do and how much detailed we need to go into is How would Lego do it? And so with that I'd just like to summarize so When we're thinking about the art of documentation It's important to make sure that we're given the users the right information at the right time So how can we not leave them down a path of here? Just install the thing and now go ahead and draw the rest of the out Instead we want to make sure that we've given them the right bits of information And then we this needs to be done as people start Engaging and start using the project and as they start adopting it their emotions change And that's that we want the documentation to be able to change with that and provide them longer form documentation as they want to Start being more productive and start being more of an expert with it It's important to think about what are the forms we can provide like can we stop doing more interactive elements? I didn't think that I am what we're doing is Catechoda or API sandboxes like with Spotify in order to give people a better experience about how they can explore and how they can start playing and If we're looking at what the read me needs to be doing it needs to be that signpost that gateway Where people can go where all the information is so people have all of the information which they need in order to make sure That they're solving the problems which the author project is doing and with that Thank you very much for your time. If you ever would like some documentation advice or meet a local at Support or send Our show ideas, please do reach out. Please do email or tweet me and with that. Thank you very much. Enjoy the rest of your conference