Technical Documentation - How Can I Write Them Better and Why Should I Care?

Hi everyone, thank you so much for joining my talk about technical documentation. And this talk will be about how can I write technical documentation better and why should I care? I of course also mean you. But first of all, hi, my name is Hila Fish, I'm a senior DevOps engineer and I work with Wix. I have 15 years of experience in tech industry. I'm a firm believer of communities and that's why I'm part of the AWS Community Builders Program and I also talk about Terraform quite a lot, so that's why I got the HashiCorp Ambassador title. I'm a co-organizer of conferences in Israel where I live, DevOps Days Tel Aviv is the biggest one of them. I'm a mentor in courses and communities, DevOps Culture Friend. I think this is what helps companies achieve great things. And on my spare time, I'm a lead singer in a cover band, as you can see in this picture, which is a lot of fun. So I think, and I really believe, that anyone can and should write technical documents, because in the... let's give you, of course, a lot of examples later on. But one example that pops to mind is the fact that in the middle of the night, if I have a critical incident that I need to take care of, and it's in uncharted territory, something that I'm not familiar with because it's something that, let's say, my team member was dealing with the most. I have this critical incident. I don't know what to do. I don't even know where to start. If I have a runbook that helps me fix the issue, or at least tells me you need to check this and this, I'm content. So I don't really care. And if I have this runbook, I don't even care that the English is fabulous or a broken English. I really don't care. As long as I have a runbook that helps me debug or fix the issue, this is all I care about. So the most important thing here is to share the knowledge, and this is why we should all write technical documentation. So I always like to say that if you can't automate it, document it. And a lot of things that we can do and share in our day-to-day can be considered as technical documents. So the first main thing which is straightforward is system logical design or a brief, but also on-call runbooks, as I just mentioned. Great technical documents that helps us solve incidents much more quickly. Code readmes. We need to explain spaghetti code or anything that relates to code, then a code readme is a good place to start. Onboarding docs. Why assign a buddy to to help your new team member if you can create onboarding docs and let the new team member onboard themselves and then they can do it themselves. They have this sense of independence, so that's great.

Project learning doc. We all have projects in our day-to-day and we need to explain things and have intentions and reasoning and document the status of the project, right, so for that we have project learning doc as well. And even slack pin messages. This, for me, also considered a technical document. Why? Because if you have knowledge to share, if something is just a blurb but it's something that people will use daily, put it in a slack pin message. It will help everyone. And I'm not saying that you have to practice all of these scenarios, but at least if you share the knowledge in one or more of them, then I'm sure that you'll be in a much better place than if you haven't shared any knowledge in any of these platforms.

So this is the part where I really like to engage with the audience and ask this question. You are far away in your computer but I will ask you and you need to be honest with yourself. Have you heard or said this sentence before? My code is self-documented. A lot of people told me, and, you know, don't lie to me, you either heard or said this sentence before, I'm completely sure of it. People said just read the code and understand what it's about. Or the code tells the story. No, it's not the case. It never is the case. You need to understand things that are beyond to just code. For example, if the code is spaghetti code then good luck with understanding the code. But anything else like why did we choose this or that or any intentions, reasoning behind writing the code as is, we need documentation that will help us achieve that. So let's really understand why write technical documents.

First of all, to reduce your work volume. And when I say reduce your work volume, you can maybe ask me, wait reduce. But if I sit down, and spend two hours writing technical documents, it's not reducing. I'm overburdening my work volume, right. So let me give you an example to explain. So me as a DevOps engineer, I deal with a lot of people. I help a lot of people, developers, QE engineers, all sorts of people. And in my previous job, they came to me and asked repetitive questions. Not all of them knew how to use Kubernetes fluently. So they said, hey, how do I troubleshoot a bug in Kubernetes? Or what is this error? And stuff like that. So basically, I collected all repetitive questions.

And then I created a document. I called it tips and tricks by DevOps. Created this document with explanations and answers to all of these repetitive questions. And I released this document to their custody.

Before the document, I got seven or eight times a day. I was approached seven or eight times a day by Devon QA. After releasing this document, it was reduced to one or two times a day. So this is what I meant by reducing your work volume. It really helps you in the long run, which is awesome.

Another thing. Self service enablement and increase the velocity. So one of the projects that I did in a previous company is migrate from a big bucket cloud to a self-hosted GitLab. And then all developers need to work with GitLab. They don't know GitLab. They need to have like a soft onboarding to know the tool. So I created a doc about how to use a GitLab in a much more concise way than what they will find online. And it really helped them adopt the tool faster and helped with the velocity in general.

Other examples for that onboarding docs that I just mentioned before also helps with a self service enablement. Troubleshooting docs, also good with that. And even Slack bot to help answers with Q and A in Slack could definitely help with self service and increase the velocity. Eliminate production incidents quicker because as I mentioned before, if I have on-call runbooks that help me solve an issue, it could also help with decreasing MTTR, mean time to resolution, help the company meet SLAs and help you get back to sleep much more quickly. So this is another reason why to do that.

Another reason, avoid single point of failure or a bottleneck, which is you. Because I will ask you this rhetorical question, do you want to go on vacation and still be available for work calls? Or do you want to go on vacation with a clear head? So I would say it here, job security is dead. Please share the knowledge. And some people say that AI will take our jobs anyway. So let's fight it with knowledge sharing. It will also help make things clear for you or the future you, because once you structure things and write them down in a clear manner, it will organize it in your mind as well. And also anything related to intentions, reasoning, anything that is not straightforward, like help anything, any help that could help you with managing systems and whatnot, it should be documented because if you implemented something now in a year, you wouldn't remember anything. So you should document it in order to help you, the future you, and also of course, other team members or other people that need to deal with those systems.

Visibility, it will attract focus to the things that you do at work, which in turn will help you progress your career. And also it will help communicate things to your managers, the extent of your work, that you are actually a team player, because if you write technical documentation, it means that you care about your team members and you want to share the knowledge. And it will really convey that you're a team player and not just some slogan that you write in the CV.

And last but not least, it will help with understanding why are we doing things in a certain way? So this is true for being an engineer in general. We need to defend the decisions that we are taking and communicate them to others. It will also develop your business mindset and will make you a better engineer because always asking why will always result in you striving for the best solution or implementation possible. So these are just examples for it. Why did I set certificates here and how do I renew certificates? Why is the model complex and not following plain code practices and stuff like that? So anything that could help you understand why are we doing things in a certain way and help you defend the decisions that you are taking is also a very important thing to document. And also why not, why people document open source and repositories and it makes more sense than to document our intentions and decisions right? So we should always strive to do that and not only the straightforward things like documenting open source or repositories.

Okay, I really hope that I convinced you by now that it's really important to write technical documents. So let's see how do we do it without having it as a burden, without having it saying that, hey, I'm not a technical writer so I can do it. You can do it even without being a technical writer and I'm going to show you a structured process of how to write technical documents in an easy manner that you can just follow and then you'll be able to write technical documents in your day to day. So first of all, you need to know your audience. Based on your audience, you will know what needs to be covered and to which extent. This is by the way, your time to plan and write in bullet points what you're going to cover in your document if you can't write it right now and then you'll be able to remind yourself what you're going to cover. So we have documents for internal use like system design, et cetera and external use. API documentation for your users, et cetera. So for internal use maintainers, what do you write about? Things that you worked on while working on them because we remember things better when they are fresh in our minds, so document these parts right now and again, if you can't, at least add them as bullet points so you will remember to cover it later. Things that bug you so other people won't run into them as well. I'll give you an example. In the migration that I did from Bitbucket Cloud to self-hosted GitLab, I opened a lot of tickets to GitLab support during the migration and then I opened a ticket three or four days later because it was in production yet so they're not obliged to reply immediately. And three or four days later, please provide logs. I'm like, okay, I provide logs and then again, three or four days, I need to wait. I opened another ticket. The same thing happened then. Like, it doesn't matter what type of ticket I open, they always ask for the same logs and the way to collect the logs are always the same. You run a command in the CLI and it collects the logs for you. So in the GitLab overview, a document that I created for my team to be able to manage the GitLab after I'm gone, not only after I'm gone, even when I'm there, but on the document, I actually documented how to open a support ticket without having this ping-pong between us and support. So I have written down that you open a ticket in this support portal. You collect the logs up front, you run the CLI command X and then you open the ticket along with the logs.

And that way, you avoid the ping-pong. Everyone is happy. You prevent other people from running into annoying things and you save time in the process. Things that aren't clear or straightforward.

So another example from GitLab. During implementation, I chose to implement a version of database of GitLab side, which is different from the default version that is in the help chart. Why did I do that? I had a very good reason to do that. So I need to document. Why did I do that? Because if not, if I'm not documenting it and someone will look at the code after I'm gone, they will check the code or they want to upgrade GitLab and then maybe they will revert my decision, but I had a very good reason why I did it. So you need to document it in order to really explain things and again defend the decisions that you are taking. So this is one example. Of course, other examples are if the code is not clear, you need to explain the flow. We're describing actual functions and stuff like that.

What do you write about? For external use, for users or consumers. So write what it is about, possible use cases and quick starts, any quirks, issues, and things to consider while using this X and any examples both simple and complex that will help your user adopt whatever you're writing about as easy as possible and as robust as possible because it's easy to cover only simple examples, but you need to also cover complex to help your user do whatever they need and not just abandon it because it looks a complicated to integrate.

Next phase of writing a technical document is to decide or abide upon documentation type. So some people don't have decision making in their company, and they can't sway the vote and they just need to follow whatever documentation type they have. So sometimes companies have docs in knowledge-based like Confluence. So they just need to go along with it. But if you have any decision making any sway that you can influence the decision, I really recommend moving to Docs as Code. I'm gonna cover it in a bit, but in general, it means to interact with docs in your IDE. Docs are fully integrated into the DevTools chain and you don't need to leave your IDE in order to write documents, which is good for our developers. But we will touch more about Docs as Code later.

Some general content guidelines that you need to follow, that you should follow in your documentation. So first of all, you should have a table of contents. It is essential for content discovery. And why is that? Because of the user flow. I actually found an article from 1997 saying that people don't read, they scan. And with the, you know, how it is these days that people are, their attention span is even less, it's true now more than ever. So this is the user flow.

The user search for something, any buzzwords that help them find whatever they are looking for. So that's why you should have meaningful titles and subheadings. Then they find some examples, some results. They scan the results. If they found what they are looking for, great, they go to the result. If not, they need to go and navigate elsewhere. So that's why you should have links in your document that will help your user find whatever they are looking for.

You can think about your documentation as microservices. Each document stands on its own, but can interact with other documents. Or not really interact, but can relate to other documents. So let's say you have how to do X documents and then you want to link to another, like if you want to read more about the system, here's a link. And then you have links and people can link and go to navigate to these documents and then hopefully find whatever they are looking for. So, that's why you should always have links in your documentation for any other content that the user might find useful.

Highlights, put things in bold because again, people skim through and scan docs and they are not reading them to the fullest, so help them do that. And use colors as possible. Some say it would be controversial because some people are colorblind less and accessibility issues and stuff like that, in my experience, I found it useful to put good things in the green, bad things or things to be aware of in red and then things to consider or think about in orange. When I used that, then the developer says, ah, okay, now I noticed it. So if it makes sense, use colors as well. Words and sentences. Use short words and more sentences rather than longer words and fewer sentences because that way it will help people skim through the document much more quickly and efficiently. And please, please, please, don't try to be Shakespeare, okay? Write simple American English that non-English speakers can easily understand.

So let's cover Docsys Code. Docsys Code basically is documentation that is written in markdown. And it is awesome because it will still enable you to have a table of contents and highlights and even colors. It is plain text, so it is human readable. It is easy to write and diff. And it is platform agnostic, meaning that you can integrate it wherever. It doesn't matter which platform you are using, which IDE you're using. You can use it however you'd like. The docs folder is in the same code repo.

So the docs are integrated in the dev tool chain and there's no need to leave the IDE whenever you are writing a documentation. You can utilize PR review to make sure that the document quality is in a high-quality state and the doc is actually exists. Because if, for example, a developer added a portion of code that he didn't cover in documentation, you can fail the PR and say, hey, you didn't add a condition to that. So we are not allowing you to merge the PR until you will add a documentation.

So both to check for existence of the condition and also to check the document quality. And what do I mean by quality? You can do all sorts of checks like same for CICD for applications. You can do CICD for documentation as well to check for any validations that there are no broken links, linters, anything like it. There are two tools that I can tell you about. I haven't tried them out myself. I only saw demos, but they are look promising. DocuSource, which also allow you to push code to a frontend to see the docs in a UI portal. And it also enables docs versioning and stuff like that. And Swim, it's actually an Israeli company. It also allows a lot of features. So these are only two examples that I know about, but you can, of course, check online for any other options that could help you with CICD and help you automate the documents creation and documents maintenance in the day to day.

And as you can see on the right, a Google style guide says that docs thrive when they are treated like tests. A necessary chore one learns to savor because it rewards over time. It definitely rewards over time. A lot of people say that the most, the painful thing in documentation is make sure that they are not stale and they will always keeping up to date. So if you introduce tests and if you make sure that they are part of the PR process, then you can make sure that the document will always be up to date. And that will be useful for any user that will read the documentation. A third phase of writing technical documentation, remember your audience. So you remember that we said that you need to know your audience. Now you need to remember them. Have the user flow in mind in and between sections and have the doc order from the most used to the earliest. So for example, guess what I'm gonna mention right now? Right, GitLab documentation. So it gave me a lot of good material for this presentation. So hopefully, this will be the last time that I will remind it, but you never know. So GitLab documentation that I've written, I had, as I said, documents for developers to adopt it, but also documentation for my team to help them manage the system itself. So I started the documentation from how to upgrade because GitLab released help charts every month or so.

So basically, that was the most prominent and most frequent thing that I knew that my team members would do to upgrade the version. So how to upgrade, I started it first. And then certificates, they will renew it only once in two years. So that was next. Backup and monitoring, again, you need to do it only once you set up a GitLab for the first time. And integrations, we had integrations with Jenkins, with Jira. Also, you do it only for the first time that you set up a Jenkins. And then, of course, I had the support and how to avoid ping pong in support. So I structured the document from the most used to the rarely used. Because again, people skim through the document. I wanted to help them do it more efficiently and find whatever they need to find more quickly. This is a very important. Concept versus tasks. You need to think about what your audience wants and basically give them to them and not confuse between the two. So if your audience wants to know something, AKA concepts, you need to have documents that cover information, background, explanations, reasoning, intentions, whatnot. But if they want to do something, AKA tasks, then the document should be a how-to. And don't confuse between the two, the concepts versus tasks. Put a link to the other type to help the other users find whatever they need quickly. So because at any certain point, a user wants to do only one thing. They want to know something or they want to do something. It really is rare that the user would want to do two things at once. So allow them to achieve that. They want to do something, have only a document of how-to. And then on the document have links to if you want to know more about the system, here's an information, here's background, here's the explanations, et cetera. So that's very important not to confuse the two and have a thin document for only one purpose, know or do. Basically last phase of writing technical document is to share it with others. You need to have a feedback loop because what's straightforward to us that we are writing the documentation, what's straightforward for us is not necessarily the case for our readers. They need to say, hey, maybe, what are those initials? I don't know about them, or I'm missing some context, or this sentence you maybe thought it's very straightforward, but I don't really understand what you wanted to say here. So feedback loop is very, very important because why do we write a documentation for others to read it, right? So if the document is currently not useful, we need to have feedback loop to get to know what are the issues with our current version of our documentation, and then fix it and have iterations in order to improve the documentation and know that the last iteration is the most useful for our users. And I started out this presentation saying that you don't have to be a technical writer in order to write technical documentation, but if you do want to perfect your English, if you do want to have a better quality English wise, or like writing wise for your technical documentation, you can scan this QR code.

I collected some tips from a colleague, I forgot the word, a colleague of mine, a technical writer, Joshua Shulgasser, and some tips that I curated myself. So I believe that you'll find some tips that will help you boost up your documentation if you want it to.

So basically that's it, and maybe you'd say, hey, I'm not a technical writer and I don't remember anything that you just said in this entire presentation. At least take this golden rule with you, provide readers with the information they need and send them back to their task as soon as possible. The conversation should always be clear, simple, and to the point. What you write is very useful and helpful as long as it is concise and clear. So make sure you do it because again, people always scan, they don't read. So help them achieve whatever they need to as much quickly as possible.

And for the managers of you, and basically it's not only for managers. I will do a disclaimer in a sec. If you want to make sure that documentation is an integral part of the task and you don't have currently, and you want to achieve it right now, because it will take time to adopt a tool that will help you with CICD and PR management, stuff like that. So if you want to achieve it right now and make sure that documentation is integral part of the task, then have a task definition of done. Once documentation was added, then you are allowed to close the ticket. And then it will hopefully be inherited in the developers or any other people that have these tasks and they need to incorporate documentation. They will have this notion of, I do whatever I need to as part of the task. I create a documentation and then I close the ticket. And then hopefully this process will help you achieve up-to-date documentation even without incorporating tools at the moment.

So I hope that now after this presentation, you will go back to your desktop, you'll write some documentation, you will update some documentation and then you can say that your code is now well documented.