 Welcome. I hope you had a good lunch and my name is Chris Ward or Chris Chinchilla, in case you're wondering what this is. It's not a mouse. It's very specific. And you'll possibly be pleased to hear this will be a container-free zone. No mentions whatsoever. Let's begin. So, I have a question first for everybody. When you find yourself at a new project, and I'm going to use project to mean software, service, product, project, whatever. Just using this catch-all term to save repeating many times different words. What's one of the first things you will look at? It's a loaded question, but feel free to shout out an answer. What's one of the top three things at least you're likely to look at? It's a loaded question, but yes. I would hazard a guess that if it's not the first thing, it's one of the, at least the top three things you will look at when you reach and you project that you're interested in. So, in this presentation, I'm going to try and give a bit of a crash course, the selected highlights, if you were, into how you can make documentation for your projects better. It's just highlights. It's not everything, but hopefully enough to just help you make what you have better. I might just, before I get to the real advice, let these people sit down. Okay. So, I'm going to begin with what I'm going to call the three Ws, which is maybe slightly, me just trying to find a convenient way of having a catchy thing to remember, but I think it actually makes some sort of sense. And these three Ws are who you're writing for, what are they trying to achieve, and then why are you writing this in the first place. And some of this is maybe a little bit of a cliche. It might be something that sounds fairly obvious thing to say, but I would also say that with most projects you're working on, if they're bigger, you've probably already looked at some of these points in product design, user story generation, and things like that. You've probably already answered some of these questions, and there's no reason they can't apply to documentation as well. So, the who is broad? It could be more than one type of person, depending where you are in documentation. Is it a blog post? Is it more in-depth documentation? Is it the intro text, the first page of the website? Is it a GitHub repository? The who may vary slightly in each case, and each person in each case will have slightly different needs and knowledge. And what are they trying to achieve, and why are you writing this? Are you trying to get people to install your project and use it? Are you trying to give it publicity? And what are they trying to achieve by installing, downloading, running your project? And as I say, hopefully during planning phases, you have already addressed some of these questions, but think about them again when writing documentation. And I guess the first point in addressing some of these is assume nothing. I think it's a safe assumption that you can assume nothing. Quite often, we assume as developers or technical people, or however you want to describe yourself, that everything we make is standard or normal, and done in a standard or normal way that should be understandable by everybody else who's in a similar place to us. But actually, in my experience, you would be surprised how different many people actually implement things, and how when you think that your unique way, sorry, and actually that your way, no matter how normal and standard you may think, is actually more unique than you may think. So, for example, in documentation, is that protocol, that technique, or that dependency that you think everyone must have installed? Do they really? Well, there's no harm in mentioning it anyway, just in case really, it takes an extra few seconds, and everyone has a much nicer experience. Again, not everybody has the same programming implementation experience in history as you. Some people might have come from an academic background, some people may be more self-taught learners. So again, don't assume that everyone understands the same techniques and methods that you know, just because you know them doesn't mean everyone else knows them. This is possibly slightly harder to address, but again, always question your assumptions. This is probably good advice for many things, but especially in documentation. Then maybe one of the next important points is to refine your concepts. Make a start by explaining in the simplest terms you can what your project does. And if you can't find a way of reducing these concepts into something simple, if you like to borrow kind of phrase from the startup industry into an elevator pitch, a three-minute pitch, then maybe try harder, try to refine your idea more. I personally actually feel that most ideas, no matter how complicated, can be reduced to a simple pitch, if you like, that everyone can understand. Of course, you're going to lose some of the subtleties and detail, but that's okay. You're just explaining something in brief as to what you're trying to accomplish, and then the person can make up their mind if that is something that they're interested in or not. I understand not everybody is good at this, so if you're not good at it, find someone who is to help you refine that concept to its real kind of core meaning for being, why you're doing what you're doing in the first place. Next, maybe slightly controversial statement, API docs are not always enough. I would generally say they're never enough, but there are actually certain circumstances where they are, which I'll come to in a minute. API documentation, it helps you describe what the components of your project do, what this endpoint and these methods do, and how someone can interact with them, but they don't necessarily describe how someone can assemble them into something that makes sense, an accomplishment, a task, a component of their own project, and this is actually a little bit dependent on programming language. For example, we've found with some tracking of what people read per language that often Java developers actually do jump straight to API documentation. We could question a lot of the reasons for this, possibly they tend to be more experienced developers, maybe they've been around longer and they don't need any hand-holding and they just want to jump straight in to the kind of descriptions of the tools, or maybe it's something else, whereas, for example, JavaScript, Ruby, Python developers actually tend to like to follow tutorials more. This also is a very hard thing to measure because maybe your Java documentation is very good and that's why they're going straight to the API documentation, but just bear in mind, again, not everybody is the same, so sometimes there are differences, but I would say that if you can, build at least a Getting Started tutorial on top of your API descriptions to help explain how to assemble these pieces together. Next, I'm going to say it's not a manual. Actually, we had recently the Write the Docs, which is the kind of technical writers conference in Prague a couple of weeks ago, and someone did a report there that showed actually there are some cultures and people, but predominantly in this, we were looking at particular cultural groups around the world that actually do read documentation no matter what form it is from start to finish, but this is actually quite rare. You probably know yourself, it has it a guest that when you come to a project, you probably read the Getting Started, you download it, install it, then you look for something specific and jump around a bit. You hardly ever, books are obviously different, but we're talking about documentation. You hardly ever read, actually, just from start to finish. So again, you can't assume that's how people will read your documentation. Also, bear in mind how people are getting to your documentation. Quite often, people are not getting to your documentation from your documentation, they're coming to it from searching for it and trying to find a particular page. It's a very common way of someone arriving at any web page. So again, you can't guarantee that the three important steps they should have followed before have actually been followed. So there are techniques, of course, to help with this. You can have navigation that guides people through. You can have links back to important concepts that they should have done already, and so forth. If you have a project that actually needs someone to follow things in a certain order, this could be especially relevant for hardware, for example. In a very interesting kind of edge case, we had one of the documentarians from Google data centers at our conference, and people there have to follow things in exact order. You can't plug cables in the wrong order. They have to go in the right order. So there are certain instances when you may need that. So find a way to gently encourage readers to follow steps in a certain order if they have to. Okay. We'll come back to this point. Now, interactivity, this is getting into a bit more of maybe sugar on top of documentation, actually. This isn't possible with all projects. For example, maybe big data ecosystem projects, it might be hard to offer interactivity, but there may be some ways too. But if you can actually add any interactivity to your documentation, it helps readers understand a concept, and in the age of most of our documentation being read online, this is actually fairly easy to accomplish. We have access to a wealth of rich media we can use. So this could be in the form of embedded code examples, interactive consoles, API browsers, or if all else fails, maybe a video or animated gif. And I've got a few little examples here. So this is an example from a database company. This is a JavaScript console with a pre-populated query. It looks like a real terminal. It isn't, but it looks like it. You can issue a query against a test server, and it brings back some results. With something like this, of course, you have to be quite careful, because a savvy developer will think, hey, this is a database. I'm going to start dropping databases and doing all sorts of nefarious things. So bear in mind that you might have to restrict people a little bit, or have like a refresh script or something like that. But these sorts of techniques are actually very effective, because not only do people read some examples, they can then see exactly how it works. If you don't want to create your own, there are things like JS Fiddle. So here's another example in the middle of, sorry, CodePen, in the middle of an example, where you can actually jump straight into playing around with the code and see changes live. This is, of course, very applicable to something like JavaScript, where it's a web technology. Not every technology will allow you to do this, but if you can, it's a very effective way of explaining a concept. Here is one from an API browser. So again, we explain the concept. You can click on the example endpoint, look at the headers and the parameters, and then just experiment to see what happens and the response that you're going to get. Of course, this is pre-populated with example data, which may or may not be useful, and we'll come to explaining examples later. But it's again a good way of seeing what to expect. And when you're doing something in your own project with this library, you can see, well, that's not quite right. This isn't how, this isn't what I'm expecting to see. Okay. Let's now move on to language. Again, this is selected highlights. This is probably an area where most people would like the most advice and you could go on forever. I didn't train in English. I trained in computer science, actually. So a lot of, it's strange, actually, I've relearned a lot of English grammar because that's the language I write in recently and understood some of the more technical underpinnings of the language as well, which has been quite interesting. And also living in another country, I live here in Berlin, has helped me question my own language as well. It's actually quite interesting. That's a whole other issue. It's mostly English examples. Some of these may be applicable to other languages because some people are better writers than others and some people are better coders than others and explaining concepts clearly is a skill in itself. I personally was a coder for quite a while, but I found whilst I could code, I wasn't the best at it. I was actually better at explaining things to people. And there's plenty of very good coders who are not very good at explaining things to people. So there's room for people in the middle somewhere. Okay. So my first one would be involve the reader. We know that often developers can be a slightly skeptical and sometimes sort of blasé group of people who like to think or we like to think that we always know better than anybody else. And so whilst writing with a more user focused approach and some examples that I'll come to can sometimes come across as a little bit demeaning or patronizing, if you're not careful, if you can get the balance right and done well, it can be quite effective. So let's have a look at some examples. So here is a perfectly good explanation of a function. Function takes parameter X and returns value Y. This is just an example. I'm not spelling out exactly what it's doing just for an example. It's clear. It's understandable. It's fine. Let's have a look at maybe a different way we could write this. So in this case, you can use function to return the value of Y based on X. It's a small change. It's quite subtle in some respects. But what we're doing is we're putting the person reading the document in kind of a scenario and involving them in the narrative. And incidentally, you could use we in this example too. This is actually a personal preference. But it often comes also comes down to consistency. Once you've picked one, stick to it. And it's a very kind of simple fix. And I must admit, when I first started trying this, I was a little skeptical. I've only really been trying this technique for about the past six months. And again, when I would read technical documentation, there was a lot of sort of you can do this and you can use what we're saying here. I initially did find it a little patronizing. But actually, firstly, it works quite effectively. It does work quite well. And also you start to find your own writing gets more fluid as well. The flow of your own writing actually starts to become easier and feels better. It's a tough one to get the balance right. And for example, there may not always be a person as the thing being involved. It may be a system. It may be that the server can use function to return the value of Y based on X, et cetera. So when we're writing technical documentation, we're not writing fiction. But there is no harm in trying to tell a story in a limited capacity, of course. There is a bit more we could do here. For example, we could include examples. So you can use function to return the value of Y based on X. We could make this more clear what could a person be trying to do in this case. Picking examples is actually quite a challenge in itself. Because you have to decide, do you pick an example that is too specific and the reader just looks at it and thinks, well, that's nothing to do with what I'm doing. This doesn't make any sense. Or do you pick something too simple that people don't understand the level of complexity you could go into? So it's actually, it could almost be a talk in itself. It's quite complex to get it right with the right data. There's also, I keep referring back to the conference we had because it's fresh in my mind, we had someone who does documentation for Atlassian and they describe what they call the right level of wink, which is a slightly odd term, but adding in a bit of narrative and a bit of fun, but not too much. And again, it's a difficult balancing act and it depends a little bit on your project. So I'm just going to jump into a little bit of technical explanation of what has happened here and try to break down what we're doing. It's actually an example of passive versus active voice. And it's more of a grammar style than a concrete rule. And again, as I say, it's up to you. You don't have to use these things. It's not, English grammar does not say, you must do this. It's up to you and how you feel things feel better. But in my experience, it has worked quite well. So here is this example again, worded slightly differently. So function can be used to return the number of Y based on X. Again, it sounds pretty similar. It still sounds, I think, better than the first example. What is wrong? I say there is nothing wrong, but this is an example of passive voice. And this is, I'm not entirely sure if other languages have this kind of this problem, but it can come across sometimes as sounding a bit withdrawn. And again, in technical communication, this is not so important. But let's think of this more sort of human sentence and see how it feels. So holiday approval will be notified in due course. This, I hope you agree, does sound a bit cold and withdrawn. If I got this from someone, this makes me feel a little kind of, first thing I'm a bit unclear about what's happening. And secondly, it does seem a bit like they're just trying to get rid of me. This actually is an example of this, which is very popular in British English. It's called passive aggressive. This sort of almost trying to push away responsibility of the sentence or from anybody, really, there is no responsibility in this sentence. No one is doing anything in particular. And yeah, it also is often used in business speak to sort of step back from any kind of responsibility again. So what could be some examples here, how we could make this a more active sentence? I mean, an example I thought of was something like the HR department, for sake of argument, will notify you about your holiday approval in due course. It's still not fantastic, but at least we know who is going to get back to us and we feel like they're doing something. And that's kind of the difference between passive and active. Putting an actor in the sentence to make it feel like something is doing something. Next, I would say, keep it short. And I'm not going to say keep it simple because we are writing technical documentation and some things are just complex. But complex doesn't have to mean verbose, rambling, unnecessary, long, overly wordy. And this is actually harder than it sounds. It is sometimes easier to write long copy than short copy. One job I had a very long time ago was writing 80-word reviews of music CDs, which shows you how long ago it was. And that was really hard. Trying to distill a hour-long CD into 80 words was very difficult. And this feeds back a little bit to one of the earlier points. If you can't explain a concept succinctly and shortly, then maybe, and here is where I might be slightly rude, I apologize, maybe you don't understand your concepts enough. And you need to take a step back and examine what you have more and get it to the point. There's a couple of little tricks here. So, for example, on an overall level of keeping it shorter, reduce the copy to just what needs to be said and don't repeat yourself. There's also a lot of smaller-level things you can do, shorter phrases, and there's many of these. And English especially is very good at having shorter equivalents to longer phrases. And this is actually interesting. I spent a lot of my time editing in some jobs, editing text, English text from German speakers, but also I spent a lot of time doing it from Albanian speakers and Indian speakers. And they all have their own kind of translations of phrases in their language into English, which there's lots of patterns. And this is a separate talk in itself. So, for example, a very common German one is in order two. In English you can say two. And that cuts out quite a lot. So, there's lots of the little things that you start to spot patterns in your own writing that you can cut out. And there are tools that can help you with this, which we'll come to later. And just to wrap up this little section, here is a great catchphrase. No one is exactly sure who said it. But it's very true. It is quite hard to write something short. And it is a skill in itself. So, let's have a look at structure. I mentioned earlier that readers can enter your documentation at any place in a documentation. In fact, I lied. It gets even worse than this. There have actually been many reports to show that in online reading and eye-tracking experiments, most readers, and especially of technical content, and I bet at least 90% of you could say you've done this, all you do is look at titles, look for code blocks, and then go somewhere else. Does everybody pretty much do that? Yep. So, I've pretty much just said here's how to make your documentation better. And now I'm telling you, no one's reading it. What can we do to improve this? Okay. So, here's an example. And I will say, so I spent a little bit of time working for a technical blog as well, which is ad supported. And ad supported sites actually sometimes do a better job of this because they have to, because that's how they're paying the bills and the wages, so they have to be better than sometimes internal documentation. So, here's quite a nice example. It's a reasonably sort of reasonably complex topic. It's quite long. But I'm going to scroll through. And we can see, actually, when it plays, here we go, it's got lots of nice headings and subheadings and notes, code blocks quite regularly. Again, lots of subheadings. It's quite long. But we can elements of the page jump out at us. And we can use these through careful kind of dividing of the page. And we can actually see like paragraphs of text usually tend to be fairly short, meaning that we at least have a better chance of getting people to read what we have by segmenting up this page as much as possible. And I mean, personally, this sometimes feels like it's a step we really have to go to, because sometimes it feels like a step you don't even want to do. But it is the sad fact, and we've all just admitted to it, that people spend a lot of time not paying much attention to the bodies of text. So it's a way of making sure people do as much as we may not like it. Consistency. I'm quite a big believer in consistency, in documentation, and what you define as the rules of consistency. So your style guide, your technical language guide, whatever it may be, maybe a marketing style guide from the company will be up to you and your organization. But when you have decided on it, try to stick to it. So for example, looking at the active voice example, if you decide to stick to you, always use you. Don't use a mixture of you and we. Unless, of course, you are referring to you, the reader, and we, the company. That's a different case. But or if you have a company name, a project name, a way of describing a particular technical element, so for example, do you refer to an instance or a node? Do you refer to a cluster or a group, etc., etc. Once you've figured out the terms you're going to use, stick to them. And this is often because when you're using inconsistent terms, it can be quite disconcerting for a reader because you're not sure if it's referring to the same thing or not. And this doesn't mean that you or your team, if you have a team of writers or contributors, have to write like machines with no character. It is possible to balance the character with style. Okay. I think I'm running slightly early, but we'll see how we go. Tools. I'm not actually going to go into too much detail on tools because technical writers, much like developers, love to argue about this endlessly. And I don't really want to get too distracted by that discussion. I might tell you some of my personal preferences, but it's really up to you and what works for you. And also, yeah, it depends on your platform, your language, etc., etc. So formatting and editing. Most technical writing is usually done in some sort of plain text format. I've met very few technical writers who use anything like Word or the equivalent. But there are actually quite a few who use Wiki-like tools. Confluence from Atlassian is actually surprisingly popular. But also like Media Wiki, the sort of underpinnings of Wikipedia and some other examples are also popular. So what these markup languages tend to do is separate out the writing from the formatting and try not to distract you too much. And this is one of the reasons we don't like to use Word. Most people's first memory of Word is opening up a document and being confronted by buttons everywhere. And you get distracted by trying to make something look nice instead of actually on the writing. And the plain text options kind of just abstract that. If you want to set a heading, you set a heading. What the heading will look like is not really your business. It's up to how the documentation is rendered in the long run. So it's separating these concerns of content and display. So personally, I like a format called Markdown, which is reasonably well known. It's very simple. It defines a limited selection of formatting options for your text. And you just write. And actually, to be honest with you, when I first started using markup languages, I was a switcher from Word and Pages and things like that. Initially, I was really skeptical. I thought, what the hell is this rubbish I've got to write? And I can't do anything here. But within a few months, it really blew my mind how much more productive I was being. And actually, personally, I use Markdown for almost everything. And even writing letters and things like that. Because it just gets out the way and I just write. And it's a really nice focus. Markdown has its limitations. If you need a little bit more complexity over layout, if you want to be doing things like note blocks or defining code blocks in a different way or more complex tables, you might want to look at things like restructured text, ASCII doc, and there's a whole bunch of XML-based documentation formats as well, which you'll probably know if you need them. Or you're working at a company that is often working in a kind of more enterprise proprietary ecosystem and is using these tools. But a lot of them are open source, too. And when it comes to editing, again, lots of text editors. I think text editor versus text editor is one of the oldest arguments in development. I personally love Atom from GitHub because I'm not a coder, so I like things that look a bit nicer. And at the end, you can see my blog and I wrote a post recently about how to customize Atom for writers. And it's actually been a very popular post. But there's many others. And the great thing, again, about using plain text formats is if you are also a coder, your editor, and even IDEs probably will also support many of these text formats. So you don't even have to change environments to do any writing. You can do everything in the same place. And again, a lot of these tools will have expandability options. Of course, there are expandability options for something like Word, but it's a lot harder, whereas writing expansions for text editors is fairly straightforward, he says. Management of documentation and displaying documentation. So much like the code projects, the code of the projects we're documenting, it's also a good idea to manage your documentation. Likely in something that at least resembles version control. This is important firstly because often documentation is a combined effort as well from teams. It's not always just one person, much like the code. It also allows you to version the documentation. Sometimes when you introduce a new feature into a new version of a project, the documentation needs to reflect that. But you might also have a lot of customers on an older version that doesn't have that feature. So you have two versions of the documentation. And if you're version controlling and organizing your code into branches or tags or whatever else the concept might be, it lets you separate out the different versions from each other. So, of course, anything you use for version control, GitHub, GitLab, SVN, Mercurial, Dropbox, anything else that you care to throw at it, you can use documentation too. I work for this company, if you haven't guessed, called Contentful, which is an API-based CMS. We're trying to dog food our documentation. Some of our documentation is in our platform, other bits of it aren't. We don't have our API documentation in there, but I'm actually working on trying to figure out how that could be possible. So, and then you have some very specific sort of CMSs if you like for documentation. Read the docs, which was kind of the project behind Write the Docs. It's largely open source, but also has a commercial offering if you need a bit more support, sort of sits on top of a GitHub repository, and then renders a documentation for you and handles all the versioning and things like that for you. The example I showed you earlier of the API browser is a project called Apuri, which, again, is a sort of mixture of open source and commercial, and there's plenty of custom tools, static site generators, even a content management system if you want to, wikis, et cetera, et cetera. I mean, as I say, technical writers are technical people. We like playing with tools, too, and arguing about which one is better. So, taking it up a notch, this kind of gets to sort of more interesting, exciting stuff, but also a bit more complicated. One of the other big advantages of keeping documentation in plain text is the ability to perform all sorts of things on it. The text is just text. It's not encased in some kind of container file anywhere. It's just plain text, really. So, these vary in all sorts of levels of complexity. Testing. Let's start with testing. Often in technical documentation, we have code blocks. One of the worst things, I think, two of the worst things you tend to find with documentation is it's either out of date or the code examples don't work. Well, one thing we can do is every time you build a new version of your code, there's nothing stopping you also building a documentation into some form of continuous integration or manual testing process and test the code blocks, too. There's, again, lots of options for this. It really depends on your language, your CI tool, your bunch of different things, but most languages have more than one option available, actually. But we could also test our language. This gets a little bit more interesting, and it's something I'm trying to set up at work, and no one is particularly opposed to the idea. I just haven't got around to it yet. A lot of, especially NPM, so Node, so JavaScript, and Python has a lot of little plugins, modules, whatever you want to call them, available for testing grammar, spelling, links, and all sorts of other things. So, there's even like profane language. There's a very good linter I use, and linting isn't really testing, but more highlighting potential problems for good use of English grammar as well, which I found very, very useful. And these are all just modules that can also be plugged in to your continuous integration or testing system. And if you're really bold, you could say, well, if our documentation at this build has a certain percentage of spelling mistakes or broken links, it's not going out. We're breaking the build. And I can bet you're going to annoy some developers by breaking a build for a typo, but this stuff adds up. If you have one typo, okay. If you've got five typos, it starts to look a bit shoddy, and people don't necessarily trust what you're doing so much. I've already covered linting a bit. One of the interesting things with a lot of the text editors I mentioned is you can not only lint your language, as I discussed, and the right good linter, which is an MPM module, is especially useful. You can also lint the code in your examples. So not only test, but lint your code. All the code examples you're showing kind of best practice as well. And then we come to some kind of more complex types of automation. We're working with CI systems. We're working with developers. We all know that we like to reduce as much manual steps as possible. And what's one, if you have a project with a graphical interface, what's one of the most repetitive tasks you're likely to do in documentation? Screenshots. These are great. Screenshots are very useful, but they have a couple of problems. Firstly, they take time to make. And what if you have, like for example, Drupal or CMS, it has lots of screens? Screenshotting everything could take an eternity. Also, they get out of date. Someone changes a CSS style, the button looks completely different. And okay, granted, most people will figure out it's the same thing, but maybe the change is bigger. Maybe some text has changed. It says click the enter button, and there is no enter button anymore. It's now called go. And people can't find it. So it's actually possible to automate screenshotting. And this gets a bit more complicated. And I must admit I haven't done it yet. But the clone community, which is a Python CMS, are very, very good at this. And of course, it's an open source community, so they've shared all their documentation and tooling around this. It's Python tooling, of course, because it's a Python project. But they have a very good system that screenshots everything. Every time there is a build, it runs through some screenshotting. And this can be done in a different sorts of ways, depending on the application. For example, web tooling will tend to use something like Selenium, if you're familiar with, which is a sort of driver for a browser. And you have, like, sort of, what are called headless browsers as well, which is not really a browser, but is kind of thing that can help with this. And then, for example, I know the latest Android studio has the ability to record graphical Android tests as well, visually. So the tooling varies. But if you can get this into your workflow, it'll take a bit of setup. It saves you a lot of time in the long run. And kind of continuing the automation, write your own. I've already said we're generally using maybe open source IDEs or text editors. We're using open text formats. If we want to automate something, let's do it. Let's write something. For example, the text editor I like, atom, is written in JavaScript. It's not too hard to write your own extensions. And for some examples, some I've been working on, and I've already said I'm not the best coder in the world, I wrote a plug-in to export my markdown files to medium. Because quite often I put blog posts up on medium. And now I just have a simple export to do it. It's sort of rejoining two steps we've looked at. We've talked about a style guide earlier, and we've talked about linters. And a conversation I had came up with another writer about, wouldn't it be great to automate, like, style checking? Like, a user-defined style checking. So we came up with this idea of writing a linter for internal style guides. And I haven't written it yet, but it's perfectly possible. And that will actually save a lot of time and effort. And again, we can break the builds on documentation if someone hasn't spelt or capitalized the company name correctly, or we've used instance instead of node, etc., etc. So you have this option to take things a step further and write your own. Or if you can't, you're probably working with developers who can, if you ask them very nicely. So I've left a little bit of time for questions. Just to wrap up, so if you're interested in more, then I've sort of mentioned the write the docs community. It's not the only technical writers community. Germany in particular has a tech com, I think. Correct? No one's corrected me. So I think that's correct. And other countries have these sort of more established technical writers communities. But write the docs is the sort of more, maybe the more, I don't know, I don't want to use any adjectives. Yeah, more community. Like, I don't know, it's not a professional organization. It's, anyway, I won't. If you're in Berlin, we have a meet up here in Berlin. If you're not in Berlin, there's meetups in a lot of other places. And there's a Slack channel, of course. Quite a lot of Americans. So you may always, you may sometimes have to wait for answers to your questions, if you're not in America. But also lots of other people on, especially on the write the docs website who are happy to help. And wrapping up, my kind of final point, why do all this, is that I would say documentation isn't just for developers. And I'm going to claim this quote, unless anyone else wants to, which probably not the first person to say it, but I'm going to claim it. Documentation is actually read by a lot of other people. It's read by marketing people. It's read by search engines. So when people are searching for things, documentation is read by search engines. And also, quite crucially, documentation will be written by the people who sign the checks or pay the bills if we want to use a more modern terminology. You as a developer, or someone as a developer, may find this awesome new project. They understand, they get it. They're a technical person. They say to their boss, hey, this project is great. Can we pay a monthly fee to use it? And their boss looks at it and reads it and doesn't understand what on earth it is. There's typos everywhere. There's spelling mistakes. They may be trying to download something. It doesn't work. They don't get a very good impression. So don't forget, documentation isn't just for developers. It's actually read by a lot of other people, too. And that's kind of my closing remark, I guess. This is me. I work for Contentful as the technical writer. I've only been there a month, so don't blame the docs on me quite yet. This is my personal website. And I come laden with all sorts of cool little merchandise. Sucks. And also a Rubik's Cube. So if anyone wants to ask questions, I've got goodies for you. But thanks very much, and hopefully you do have some questions. Oh, there it is. I was wondering where the microphone was. I wanted to ask you, so when you're talking about, for example, documentation with Drupal and stuff like that, where do you draw the line on where you're working with an open source project, right? And so much of that is already documented by the community. And really what you want to capture is just those customizations that you've made to it. How have you found that in the past? I find that can be a very tricky thing, because some clients, you can quite happily point to that documentation. And you really don't want to start getting into the nitty-gritty bits that are already, you know, covered all across the web. Yeah. I guess even community projects can have a style guide. It doesn't mean people are going to stick to it, but you can have one. If I would then say, if, for example, you as someone who wants to recommend a module to another project and you find that that module's documentation isn't great, of course, I can say the catch-all quote for open source communities, issue a pull request, or maybe write your own blog post to fill in the gaps and things like that. I mean, I guess in community, community, helping them out make it better is probably the best action. But unless it's a company, you can't really force people to do things. You just have to strongly suggest, I suppose. Does that answer the question or not? Yeah, a little bit. I don't know. It's the problem with this stuff. They're broad questions with broad answers. Yes. And how much, I guess, the other thing is when it comes to the problem that I find as well is trying to actually get clients to pay for the documentation as well. So factoring in how do you handle that? I have had personal experience of a lot of this because often companies get to a certain point with people just doing it themselves, and then they get enough complaints from people and support queries, often a good example to show how, while you need a writer, because you're getting all these queries from people saying, I don't understand this, and then the company will hire someone. And unfortunately, that tends to be the process. I know of a handful of companies who will say, we want to be, use a focus from the outset and we'll hire developer relations people, technical writers from the outset, but they are very few, unfortunately. Usually it gets to a point where you're like, oh, my God, no one understands anything, we need a writer. And that's unfortunately usually how it goes. Or you hire someone. Before I started working full time, I did freelance documentation. It's not ideal because you're not getting ahead enough into a project, but it's a compromise. Yeah. But unfortunately, that does tend to be the case. And especially with smaller companies, it's the thing that's left until it's completely necessary. And come and take your pick of freebies in a minute. We'll go for the next question. Any other questions or was that? And feel free to... Oh, yeah. Hi. You said that it's a good idea to keep the documentation in the version control system, obviously, I guess. Would you keep it in the same version control system as the code and ran or if ever? It depends, which is the standard answer to most technical questions. So I would say if the documentation is very tied to the code base, then keep it together. If you have, for example, like getting started tutorials, more kind of the nice to have stuff, then that doesn't necessarily always directly match to the code base. It's more broad, and that can be separate. So I've seen all... It's largely up to you and your tech team, but if you want to do things like the nicely integrated kind of continuous integration, then it'd be better if they're all in the same place, but it's not a deal breaker. But to be honest with you, there is no hard and fast rule. I would just say if documentation is very tightly matched to the code, then try to keep it together and maybe keep some of the other things separate. But I've worked with companies that do a mixture of everything. If they are separate, try to keep the versioning in alignment across the repositories. That would be the main thing. So if your code has a version one branch, then have the matching documentation in a version one branch. But there's no hard and fast rule, I'm afraid. Two minutes, 45 seconds. Any other questions? Cool. Well, if anyone wants Rubik's Cube socks, stickers, or just would like to know a bit more about the company I work for, come and say hello. But thanks very much. And yeah, if you want to come and ask me a question afterwards, also do. Thank you.