Keeping Docs Structured and Manageable: Insights from Marco Spinello, Booking.com

Transcript:

• • 01:13 – 03:02 Marco’s Journey into Technical Writing

    Gowri Ramkumar: Welcome everyone to the Knowledge Base Ninjas Podcast. Our guest today is Marco Spinello, Senior Technical Writer at Booking.com.

    Hi, Marco. How are you doing today?

    Marco Spinello: Hi, Gowri. Thank you so much for giving me the opportunity to participate in this podcast, which I usually use as a listener. I’m doing great. And, how about you?

    Gowri Ramkumar: Fantastic. Yeah. A pleasure to have you.

    And, yeah, 15 years of experience! Just talk me through. How did you start this journey? What made you to choose this as your career path? And then we’ll dig a little bit deep into your current experiences.

    Marco Spinello: Okay. Thank you. I started by chance. It’s one of the options that technical writers have to start their career. I come from a previous career as a technical translator, where I used to translate software from English into Italian. So, products from companies such as Adobe or Microsoft. I would translate the user interface into Italian, test the user interface, and also translate all the documentation.

    Over time, I started writing small guides and how-tos for internal usage at the company where I worked. And, little by little, I noticed that I prefer to write my own stuff, rather than translate somebody else’s stuff. So I started looking around and I found an entry-level job that got me started into the, this new episode of my career. And, so far, so good. I really like it. I’m not looking back with regret or anything. Just looking forward with curiosity.

    Gowri Ramkumar: Fantastic. So well done to you. And, very, very nice to hear such a lovely story.

  • 03:02 – 05:13 Defining the “Well-Organized” Documentation

    Gowri Ramkumar: Now, when we say it’s a well-organized docs, what do you actually mean?

    Marco Spinello: Okay, I give the standard answer that most iconic characters would probably give it, which is, it depends. It depends on the audience.

    Well-organized docs usually should be as close as possible to the mental model of the audience that consumes it. For example, now I happen to be in a project that aims at merging multiple scattered documentation sites into one, more consistent, and easy-to-consume documentation site.

    And, one of the questions was indeed, how do we organize it? What defines well-organized as opposed to a mess? To do that, we did user research. I’m very lucky because I’m, I write for, I write internal documentation. My audience is mainly designers and engineers, and they are reachable because they are my colleagues. So it was a privilege and incredibly easy to organize user-focused sessions. A panel conversation and have all of that, a preparatory series of activities, to understand how the audience that I serve, see and consume the documentation.

    So in this context, the definition of well-organized was based on the outcomes of this research. And mainly, we identified their pain points. Why they couldn’t find what they wanted to find, and what mental model worked for them? How, in practice, I tried to never impose my own mental model and my own idea of well-organized.

    I tried to understand what they perceive as structured and organized, and then this definition will inform the structure and information acquisition of the documentation.

    Gowri Ramkumar: Great.

  • 05:13 – 07:40 Signs of Documentation Becoming Messy or Unmanageable

    Gowri Ramkumar: Now, are there any clear signs that your documentation might gotten messy or is becoming unmanageable?

    Marco Spinello: Oh, yes.

    Even if it’s, internal documentation, we have a very open contribution model. Everyone can open a PR and, contribute to the documentation to update or rectify information. Over time, things get a little bit out of hand. We don’t have many technical writers. But we have many contributors, and we’re very happy to have them. So we want to encourage them to contribute with as little friction as possible. This means that, to favor collaboration and contribution, we are a little bit lenient on the guidelines.

    You don’t need to do all the checks. You don’t need to make sure that everything is perfect. And, so sometimes there is the time to control and review properly, and sometimes, just we don’t have the time because we have other priorities. This approach, which is probably very common in companies that are small and large, generates an organic growth where style becomes inconsistent, where the way to, for example, describe a procedure with steps is, maybe, extremely clear to the author, but is absolutely obscure, cryptic to everybody else.

    And where you have documentation that hasn’t been touched in months or years, and that has gone out of, has become obsolete. And, also, collaborators who don’t really do any research before starting writing. So they don’t check if that information is already present. And so they tend to duplicate. And then you have documentation drift, where you don’t have a single source of truth anymore. These are all little flags. I wouldn’t say red flags, but they are yellow flags, yellow and orange flags, that give you signals that you need to do a little bit of gardening to gather this content and make it more, better structured, and easier to find and digest.

    Gowri Ramkumar: Understand.

  • 07:40 – 11:30 Building Processes That Keep Docs Fresh and Manageable

    Gowri Ramkumar: Now, you did explain about how you make everybody becoming a collaborative part in creating contents and bringing everyone’s responsibility for creating contents. But, thinking aloud, I think that also brings a little bit of chaos, right? Like, they all have styles and the contents might not be uniform across the board.

    Now, what processes do you think will help prevent documents from slipping back into an unmanageable one? After the clean-up?

    Marco Spinello: Yes. Let’s say, hypothetically, let’s start from indeed, as you mentioned, a cleanup situation where everything is bigger span and shiny, and ordered. Over time, entropy, which is how our universe works, creeps in and start messing things up a little bit. I would say that, ways in which the tech writers try to create documentation awareness among our colleagues, and of course, can be engineers, product people, designers, etc. We post blog articles, internally, we organize workshops, we do little demos. Engineers love hackathons. So we have introduced the concept of Docathons, which is basically a couple of days where a group of people, multiple teams, and it can be engineering teams, it can be designer teams. It doesn’t matter. But they will have a focus on improving the documentation corpus that they own.

    We have run a few, we have a playbook that is very basic, but it gives you all the tools and the structure that you need to run a Docathon. The results are encouraging. Besides cleaning up the documentation, what really matters in the long run? And these are the things that really are big wins from the point of becoming a documentarian, are that your users become more aware of the documentation pains, and they become more aware of how they can also mitigate them besides simply just flagging them. All these docs are, all these docs are wrong.

    Also something that I do very, very honestly and very frankly, when people come to me and they say, you know, this, this is wrong. I said, so what, you fix it? Yes. Say, but I don’t know how to do it. I said, you know, you are my SME. If I have to fix it myself, I first have to come to you to understand how this thing works. You already know the whole thing, and you know that there is an issue. Go ahead and fix it. Open a PR.

    It doesn’t need to be fantastic. It just needs to be correct. And then, make sure that, you assign a technical writer as a reviewer and there they win, they will make sure that the style is compliant with our house rules, our home style, that we run all the checks that we are supposed to run and that, the documentation that is published actually complies with our definition of this is good docs.

    Gowri Ramkumar: Great. Nice to know. I really like the word “Docathon”. Thank you.

    Marco Spinello: I stole it. Yeah, this is something that I think I stole it from Write The Docs. It was something that happened in the Write The Docs Community.

    Gowri Ramkumar: Okay, okay.

    Marco Spinello: Please, please use it as much as you can, because it’s a good thing.

    Gowri Ramkumar: Yeah, absolutely. I’m going to spread it to my team now.

    Marco Spinello: Yes.

    Gowri Ramkumar: Yeah.

  • 11:30 – 14:09 Role of AI in Proactively Preventing Messy Docs

    Gowri Ramkumar: Can’t leave the conversation without talking about AI. So do you see the future where AI not only assists but also proactively prevents docs from becoming messy?

    Marco Spinello: Yes. With mixed results. We are like everybody else. We are also tinkering with AI, with mixed results.

    And, one of the things that it can do is AI can generate documentation drafts based on a context that you can inject, in the context window, basically. It can help review existing documentation, for example, to spot any gaps in a procedure or to spot any inaccuracies. And, it can help you, it can notify you by saying, hey, actually at the code has been updated, but the docs are out of sync. It’s something that is kind of working, but not always right.

    Yeah. Either we are doing everything wrong, and everybody else on LinkedIn has amazing results when they post their amazing achievements with AI. But I think that the actual state of things is more in the middle, where we are using AI a lot to help us to or to enhance our processes and sometimes there’s no time to look at it with a critical eye. Or there’s too much faith in the powers that AI can bring to or to improve a process or to improve documentation.

    For example, if you want to check just the freshness of documentation, you could start, you could even consider not using AI, but just start with a cron job that checks the timestamps of the published documentation every three months or every six months, and then, produces an automated email or a slack message to the person that owns the document, or even better to the team that owns it. In my experience, it’s always better to set teams as owners of documentation because people come and go, and team have a slightly longer shelf life, let’s say in a corporate context.

    Gowri Ramkumar: Alright.

  • 14:09 – 16:11 Balancing Cleanup and Freshness of Docs

    Gowri Ramkumar:

    I think my next question is somewhat relevant to what we are talking now is, how do you decide what to keep, what to archive, and or merge when it comes to reorganizing?

    Marco Spinello: Okay.

    Well, the easiest thing when you use analytics, for example, you see if you see pages are to have very few views, in the last six months, in the last year. You may consider two things.

    One, the page is really useful, and it’s up to date. I’m 100% sure about it, it’s so hidden, is so nested in documentation that people don’t find it. So that count is not discoverable. Or, you could also review the content. Either you judge yourself because you are familiar with the content in question, or you liaise with an SME to validate the quality and the freshness of the content. And in that case, if you or the SME decide that page is old, you can flag it for archival and then deletion. So few views, pages that haven’t been touched or updated in longer, in more than 12 months, are good indicators that good. Yeah. Easy indicators of documentation that can be archived and purged.

    Also, if you can, if you have the luxury of reaching out to your audience, ask them, you can, for example, isolate a small set. Be always very specific in your asks to your audience. Otherwise, you just overload them with too much stuff to decide about. But, you know, I have these three articles and they are still current. Are they still relevant? If they say no, flag them for archival. I don’t say immediate deletion. If you can archive them first, keep them there for, I don’t know, six months, and then delete them.

    Gowri Ramkumar: Nice one.

  • 12:56 – 16:33 ⚡Rapid Fire Round

    Gowri Ramkumar: So moving on to the Rapid Fire round, Marco?

    Marco Spinello: Yes.

    Gowri Ramkumar: Please share some valuable resources you have come across recently that will be of great value to the audience.

    Marco Spinello: Well, the Write The Docs community. Always. That is my lighthouse. They have a very active Slack community. They have conferences in the US and in Europe. I think also in India. And they have chapters in Africa and, in Kenya, I think in Nigeria. Unfortunately, the Australian conference will not be held this year. But the community is incredibly active and supportive. So I would definitely recommend that.

    And then, you know, the usual blogs, the usual suspects. I follow Tom Johnson, Sara Moore, Fabrizio Ferri Benedetti, and a few tech writers that I follow on LinkedIn.

    I try to minimize, let’s say, the amount of noise that I get from social media. So I focus only on the people that I know, usually have something valuable to share when they share a post.

    And I recently bought, Docs as Tests by Manny Silva.

    Gowri Ramkumar: Okay.

    Marco Spinello: So that’s the next book I’m gonna pick up for reading. I’m a little bit behind, and I’m really looking forward to start reading that book.

    Gowri Ramkumar: Alright. Thank you so much. That’s a lot of resources to take away.

    Marco Spinello: Yes.

    Gowri Ramkumar: Now, one word that comes to your mind when I say “Documentation”?

    Marco Spinello: Well, I would write it as a word which is “Can’t find it“, which is what most users tell you. It doesn’t matter how much you order and structure, and how much you think you have made your documentation discoverable. There’s always users can find it, and it can be frustrating initially.

    You have the right to feel frustrated for 30 seconds. But then, you know, compose itself, count until five and ask why? Which is the one of the most powerful words in English. You always ask why? And, usually, they can help you find out why they couldn’t find that thing. It wasn’t in the wrong category, the tagging was incorrect, or it was too nested, as I mentioned earlier. So, that is really the first thing that comes to my mind when I think about documentation.

    Gowri Ramkumar: Okay. That’s brilliant. Can’t find it.

    Marco Spinello: Can’t find it.

    Gowri Ramkumar: Now, a piece of advice you would give to your 20-year-old self?

    Marco Spinello: You’re not the only person in the world that has imposter syndrome. We all have it.

    Every time I talk with or I talk or write or chat with other fellow tech writers, also software engineers, engineers that, in my opinion, are absolutely stellar and amazing. Amazing human beings and incredibly competent. They all have come imposter syndrome.

    They all say, oh no, I just fly by the seat of my pants. What are you sure?

    I wish I’d known that when I was younger.

    Gowri Ramkumar: Okay. Alright.

    Now, I think we managed to grab some of your experiences and, thought processes in this field. But, as I mentioned, you’ve got ample years of experience as a technical writer, but if there’s anything I have missed, please feel free to add now, Marco.

    Marco Spinello: The last thing humour in documentation. It’s really hard. It’s very debated. I’m not a serious person. Honestly, I’m professional, competent, but I’m not serious. So I use Easter Eggs in my documentation.

    Gowri Ramkumar: Okay.

    Marco Spinello: I usually, I hide links to memes or GIFs from Giphy. Hidden in a little piece of documentation, which is usually punctuation. I use a comma or a full stop as a hyperlink. And, when some of my users find them, they’re really like them. Then, of course, it’s all silly stuff. But it’s a nice breaker that gives a little levity when somebody probably is tired, frustrated, and trying to find a solution to a problem that tackling.

    Gowri Ramkumar: Great. Yeah. Well, that’s another nice tip. Thank you so much.

    Marco Spinello: Thank you very much, Gowri. Yeah.

    Gowri Ramkumar: It was a great pleasure talking to you, Marco. I don’t know how the time went, but…

    Marco Spinello: It flew by.

    Gowri Ramkumar: Yeah, yeah, yeah.

    So many good things to take away. And thank you so much for all the resources you highlighted in this chat.

    I can only wish you all the very best for the current project and whatever you’re planning to do in the future. So let’s stay in touch and have a good day.

    Marco Spinello: Absolutely. Thank you so much, Gowri, for having me. And I’ll keep following the Knowledge Base Ninjas. It’s a great podcast.

    Gowri Ramkumar: Thank you! Thank you to all the guests, in fact. Take Care.