In Pulse, a madewithlove podcast, Andreas talks with leaders from the tech startup and scale-up ecosystem. There are also some podcast episodes where Andreas talks with his own colleagues about everything he comes across when working as a CTO in residence for various clients. Sit back and enjoy Pulse!

Episode 8 – Outdated documentation

In this episode of Pulse, Andreas talks with Christophe Pasquier, founder, and CEO of Slite, about documentation and its lifetime. They also discover a new startup idea when discussing managing and maintaining documentation. Sit back and enjoy the show if you want to get started with proper documentation!

Listen to the podcast on your favorite platform

Podcast transcript – What about outdated documentation?

Andreas: Hello, I’m Andreas. In this episode, we’ll talk with Christoff Pasquier, a Frenchman living in Berlin. He’s the founder and CEO of Slite, and we regularly run into each other at conferences, and we share one obsession, which is documentation. Welcome to the show!

Christophe: Thanks a lot for having me, Andreas.

Andreas: You’re welcome. I would like to discuss today something that we both care about: the expiration date on documentation. Most companies understand they need to write documentation but fail to keep current. So you have lots of things to say about this subject?

Christophe: Yeah, I do. It’s right where our product is. Expired documentation is one of our main strategic focuses. So definitely like something interesting to me. To put a bit of context and why it matters for us at Slite: we are a documentation tool made especially for teams that work by writing. There are typically remote teams and all working teams that aim to have documentation in the same place, including project communication, interviews, modules, asynchronous communication, and discussions.

And so this problem of expiration date and lifetime of a document is key to our product. The first version of our product was called Note app for teams. 

So the idea was really: Confluence sucks. The status quo was to have this small book, almost a leaflet of 200 pages, in teams. That was on the bookshelf. One person maintained it for 1000 readers. The person in question that was the maintainer was someone other than the matter expert. 

So you had a small book with a minimal amount of information, not up to date, not written by an expert. Naturally, people were only looking at it once and never again. And so, the goal of having a main knowledge base, accessing information, and finding new answers was only possible. 

Right now, we are close to this. We’ve made a big leap in the last few years. Many teams started to work by writing everything, like their project specs, interviews, and sometimes customer docs,… all in one place. That’s a massive plus because you can search and organize them now with the database and clear structures.

But the problem was that people needed to maintain it properly. They could not add more to it because they were afraid of updating. And we are in a scenario right now that is even worse: there is so much data, so much shared information that after the honeymoon phase of documentation (1-2 years), nobody can find anything up to date, like it’s impossible to access information that you can fully trust. 

Andreas: What’s your solution to it, then? Cause it’s something definitely that we also face. We also have extensive documentation on how we work and try to revisit it regularly, but it’s tough to keep track of things.  

I’ve seen clients struggling with it as well: for example, someone is responsible for the documentation, but things need to be updated massively before you know it. And they need to be more expert on what they’re writing on. How do you make sure that documentation is up to date? And how do you mark stale documentation?

Christophe: There are three steps. First, you need to have your team using the tool daily; else, they will never challenge documentation and update it. That’s the transition from Confluence to Slite. If you have your documentation in the same place you work, you will use and update it. Use it daily.

The second kind of thing is that you can mark the status of the documentation. (Handy during the shipping process). This way, you can tell which content will get outdated after x months. After setting the date and having a clear owner, every doc has a few parameters that keep the overview. 

The owner can ping others when they notice the document is no longer relevant or missing information. New readers can inform the owner immediately if things need to be updated. 

Andreas: How do you know it’s not up to date? A doc can be very old but still up to date. 

Christophe:  That is interesting in this scenario: it’s purely social network style. The verification is expired, but the content may still be relevant. It’s up to the owner to judge and review this. But this is fundamental behavior. 

But this is part of the future path of Slite and what we are thinking about to improve this. We want to avoid creating static Wikis. We want a world where everything is documented in one place, which is a huge step. This might become a problem; an overload of docs in one place might get messy. 

There is a ceiling: if you are 200 people in a team and expect to work like a 30 people team using Slite for everything, you will create like 30,000 documents yearly. Even the best structure and search in the world can only manage some of this information with a form of segmentation.

The next step is making the marking documents smart with a mix of intelligence and heuristics, some AI, and dedicated features. We are working on it. This is what I love to think about daily. 

Every document has a halftime value, right? So in a nuclear engineering environment, an atom disintegrates with time. A metric is how many radioactive values they lose over time: you create an inverted exponential curve representing the document’s stage. 

I have a weekly leadership meeting with a lot of important information, but I have a new one next week. This new meeting only carries 20% of the value compared to last week’s meeting. If you use this idea in project specs, you create cycles of a month.

Most specs have a lifetime of one to two months. After one month, they usually lose 50% of their value. After 3-6 months, there were so many changes that these items written back then had no real value.

Andreas: Does that mean you should be able to configure it per document type?

Christophe: Yeah, the document type will play a part. 

We should have an explicit feature in the interface where you can indicate the lifetime value of the documents combined with suggestions. We also classify the document. If you have 2022 in your title, it’s a strategic document for that year. Next year it will be useless. 

If you have a date, it’s probably a meeting doc, and here goes the same. You can tag all documents and decide on value and types with smart automation and intelligent suggestions. The final step is to remove these documents from the search. 

You then introduce the concept of deprecation, marking parts of the content as useless (deprecated).

Andreas: What happens with images or videos in documentation? For example, product documentation where you have like a walkthrough video of a product. The product changes over time while documentation stays static. How should people approach that? Do you update the video every time that feature changes, or do you have like some kind of thing around it? 

Christophe: There is no good answer yet. It’s an odd problem to solve, and this specific problem of a product deserves almost a unique solution. 

Andreas: Here’s a startup idea someone can grab and start building!

Christophe: I’ve seen something like in the last few weeks trying to achieve that. You have this flow, but the app’s screen was refreshed with the previous version. 

Andreas: In the end, there will always be a manual for people to go through everything and to flag it as updated or to review it. It’s not that you can fully automate it. 

Christophe: Well, I think you can. Take a Google photo product manager; in an interview, they showed how they used AI (in the right way): creating albums when I type a location or offer all the pictures of a specific friend. It will group similar subjects, suggest which ones to keep, etc. AI does many very clever things, but the question is: what do you think about that? AI can be everything and nothing.

Start by showing me all the documents where I’m the owner. Now show me the highest level route and find the folder with the most things inside it. Auto-tag everything that has lifetime value. Now, start a new organization with only the relevant information, have a backup of everything, but start fresh. It’s a lovely idea, and your pseudo-automatic suggestions can become powerful with the right metrics. 

Andreas: Google solves it already by “only showing results from the last year.” The internet has the same issue, where there are ancient websites that might still be relevant, but a lot of information is just plain old and outdated. But I think many people are actively working on improving this because there is room for that. 

Andreas: If someone needs to get started with the documentation, is there something they can do to make the lifetime of a doc longer from the start?

Christophe: The basic is learning to write less. Everybody writes way too much. Technical refactoring is the same: remove all the spaghetti code and add something small that adds value. It’s my everyday fight, not to be precise, everything. Don’t write books for documentation. The person that reads it probably does not need to know everything. They want just one job to be done. The users are usually smart enough. Keep it concise.

Andreas: True, writing a short email is much more complicated than writing a long one. Thanks for being here!

Listen to Episode 8 on Anchor.FM