loading...
Cover image for Where should you put the documentation?

Where should you put the documentation?

nicoespeon profile image Nicolas Carlo Originally published at understandlegacycode.com ・4 min read

"Of course, there is never any documentation…"

This is the typical experience of a Legacy codebase.

Sure, documentation is not fun to write. It often feels like a waste of precious time, because we know. The problem is: we forget.

Documentation is never a priority for your project stakeholders. There are features to ship and bugs to fix! And then, one day, the lead developer who was working on the project for the last 5 years announces she's leaving in 2 months. You now have 60 days to learn how to live and work without her.

So you start thinking about documenting everything she knows, all of the implicit knowledge. And very quickly comes up the question:

"Where should we put the documentation?"

Should it be specific to the team? Should it live in the company's Confluence? Should you use the wiki that comes along GitHub/Gitlab? Are there tips that can help you? Traps you should avoid?

Let's pause a moment here to think about what makes great documentation.

The 3 traits of great documentation

1. Easy to find

If knowledge is spread across wikis, google docs, emails, and Jira tickets, people will have a hard time finding the information they need.

How do you know if documentation is easy to find? Well, there's a typical symptom when it's not: people frequently ask questions about things your team knows. Often, questions are the same. Because it's not clear where they can find the information by themselves. Hunting for the answer will take longer (and more efforts) than raising the question and wait. That's a waste of time. Good documentation would fix that!

When it's clear where the documentation is, and it's easy to search for specific information, you see less of that.

Aim for having your documentation in a single place. A powerful search feature is a must.

2. Easy to read

Basic formatting matters (and is usually given by most tools).

But think about images, diagrams, and code. Are they easy to read? Is there a way to make some information stand out? Is there a way to hide details that would not be relevant for all readers?

Adding information is simple. Keeping it relevant takes practice. Going to the point is a hard skill to earn, but it definitely worth it. Remove from your documentation what turns out to be unnecessary.

Keep information short, easy to skim. Make people practice writing docs.

Speaking of writing…

3. Easy to write

This is usually overlooked, especially when it gets spoiled by heavy validation processes.

Let me be clear on this one:

The more friction you add to the process of updating the doc, the less updated it will be.

Out-of-date documentation is untrustworthy, making people fall back to asking others instead of trusting it. Out-of-date information should be updated or deleted.

Get rid of useless information. Add missing ones. Make newcomers update the onboarding documentation. Take questions as chances to clarify the doc!

If updating the doc is frictionless, you'll save your team a loooot of time.

You don't need a validation stamp from the Tech Lead to update the doc. Anyone should feel entitled to do it.

2 things can help here:

  1. Change history will make you stop being afraid of losing information by someone accidentally removing it.
  2. Frequent backups, in case something goes wrong

Trust people in doing their job. Let them update the doc as if it was a living document.

OK, but WHERE to put the documentation?

Following these 3 traits, I'd recommend keeping your documentation in 2 places:

  1. Everything that is codebase specific should be versioned along with the source code. Instructions to help people work with the codebase should be here, in some README. I recommend you to document your architectural decisions here, with ADRs.
  2. Everything else should be in a single place. The exact solution doesn't matter. What matters is that it's consistent.

That is, if your company uses Confluence, then use Confluence. If there's no company standard on this, then make a decision for your team. Make it clear that all the documentation would be here.

What would be the best solution for documentation?

If you don't have a place to put your documentation yet, or if you've decided to migrate from your existing solution, you should be looking for something that makes documentation:

  • easy to find
  • easy to read
  • easy to write

As of 2020, I recommend going for Notion. It ranks best in most of the characteristics that matter for building handy documentation, especially if you're working in software.

Listing all reasons why Notion is my preferred choice would fill another blog post. But in short:

  • their search feature is powerful enough to make it easy to find information
  • they handle formatting, embedding images, code syntax highlighting, calling out important bits, and hiding less relevant ones
  • the content is editable in place, making it a breeze to write
  • anything can be turned into anything else, so you can just dump what's in your head and then turn it into a more sophisticated page later
  • comments and assignments make it great for collaborating
  • they backup your content with change history, so you can go back in time if some information was deleted

If you're curious, have a look at my showcase of useful Notion features for building company documentation.

Regardless of the solution you choose, don't get caught with perfectionism. Done is better than perfect. As long as you start putting useful knowledge in a single place that anyone can update, you're doing great!

Learn to understand Legacy Code with my weekly newsletter

Posted on by:

nicoespeon profile

Nicolas Carlo

@nicoespeon

I'm a web developer who loves to meet people at meetups & conferences 😃

Discussion

pic
Editor guide
 

After years of creating documentation sites, managing wikis, and writing READMEs, I absolutely agree that documentation should live with code. We have started exporting documentation from our Kotlin codebase with Dokka, which encourages good Javadoc style code comments that help you set some context for what your app/library is doing.

So I say:

  • README for project/repo/library overview, and hopefully a tool like GitHub for hosting it for everyone
  • Javadoc-style comments in the code to set context for what is happening here in the code, just a little bump to your (hopefully) self-documenting code
 

Hope you don't mind, I felt inspired to write my own post on the parts that resonated with me and I embellished with links and screenshots for some platforms

dev.to/michaelcurrin/where-do-my-d...

 

Spot on. In my team we use Google Drive, Wikis, repos, Jira, even a bit of Confluence. And we often don't know where to put something because it will get forgotten about.

We've moved to a repo and its Wiki for cross repo documentation which is a great step to keep things central.

The problem is not everyone in our org has GH access.
Some of our teams also turn a repo of docs into a docs site which is for other teams to read and is accessible over VPN so that's nice. But of course it has overheard to maintain.

 

Yeah, it's absolutely crucial that updating documentation is a no-brainer for everybody in the team. If this is not the case, the documentation will deprecate and rot very soon.