Comment by koliber | Hacker News Reader

Comment by koliber | Hacker News Reader

Documentation needs to be maintained. Period. There are no shortcuts.

When people join your team, stress this point. In the onboarding, require them to make at least one change to the documentation during their first week. People tend to think that documentation is someone else's responsibility, and it just isn't so.

The main problem is not a lack of documentation, but being able to find it. Search is woeful in all the documentation systems I've used. The only thing that can save the day is proper linking of related articles.

By default, people tend to throw documentation into a hierarchy. While that works for many things, it creates a structure that ultimately makes it hard to find things. Most documentation is related to a few different areas or domains, and with a hierarchy, you can only put it into a single "folder."

Any time you add a piece of documentation, you should link to it from at least two different places. Spend a moment and think about the person who will look for the thing you just documented. Where are they likely to look for it? Link it there.

If you ever look for something like OP, and can not find it easily, but ultimately do find it, add links to it in the places you looked earlier.

Over time, if enough people do this, the documentation will get decent or even good.

It's a solved problem in the sense that there is a solution, but the solution is not automatic. It requires someone to manage the process and the people to keep the documentation in a good state.

I wrote an article about this some time ago: https://koliber.com/articles/engineering-documentation-best-...

> People tend to think that documentation is someone else's responsibility, and it just isn't so.

What is everyone's responsibility is no one's responsibility.

I've been at places with good documentation and at places with bad documentation. The places with good documentation have someone (or maybe a team) with responsibility for documenation. It could be a developer, it's better IMHO if it's a technical writer. They don't need to write all the docs, but they're in charge of editing and organization, and checking to make sure docs are current and assigning people to update them/provide information so they can be updated.

If your org lacks a documentarian, you'll get chaos documentation, which tends towards poor documentation; this is a choice. If your org has a documentarian, but they don't have time to do it, your org has chosen other priorities over documentation. If your org doesn't include documentation in evaluations, it's not an org priority, and that's a choice, too. I've been at places with a self-appointed documentarian, and that can work too, as long as they can cajole others into doing the tasks that they assign.

> What is everyone's responsibility is no one's responsibility.

On teams that I run there are many things that are everyone's responsibility. Here are some of them:

- Everyone is responsible for showing up on time

- Everyone is responsible for being respectful

- Everyone is responsible for maintaining documentation

I would not say that saying that everyone is responsible for something automatically makes it that no one will do it. Managers and peers need to work on supporting these responsibilities.

I agree that documentarians do pick up a lot of the slack, and one or more are needed to make documentation useful. However, it is not solely their responsibility to maintain documentation. Everyone is a domain expert in some area, and they need to own the relevant documentation.

> - Everyone is responsible for showing up on time > - Everyone is responsible for being respectful

These two are usually an HR issue, the third isn’t. So unless your org makes lack of managing documentation an HR issue like the other two I don’t see the relevance.

All three are company and team culture issues. If you delegate all culture responsibility to HR you'll end up with a hot mess. Culture needs to be fostered on every level.

If you do not have backing from HR and senior management the issue will not change even if you tried.

Action without consequence causes these problems. If an employee is allowed to continually be late and rude it really does not matter in any way whatsoever if everyone shuns that employee culturally because the implicit statement is that that behaviour is acceptable but unwanted.

That is the exact situation you get into with lack of documentation, if a single employee never does correct documentation but there is no real repercussions it does not matter whether the “culture” is documentation, you have agreed by contract at that point documentation is not a requirement.

If you make it a matter of “Do the documentation correctly or we will be having talks to remove you” that clearly indicates it is not just lip service but is actually enforced culture.

Thinking the carrot will always work is part of the “documentation culture”. Make it a hard requirement or don’t do it at all.

Motivation, education, and enforcements are key.

While support from HR and senior management is helpful, I've found that most of the work happens at lower levels. In the end, it comes down to working directly with people to help them do documentation well. In engineering departments I've led, I did not need permission or enforcement to do good documentation from company execs or HR.

The "stick" that HR provides is a tool of last resort. At the same time, companies are different and what works in one might not work in another.

You don’t need permission but you need authority. Maybe you are US centric in a US state with weak employee protections so you can make those calls. In other jurisdictions it is a significant amount of paperwork and procedure to get rid of even an underperforming employee.

Totally agree, search is the real bottleneck. Linking from multiple places is such a simple but powerful habit, but again, I guess it comes down to people being lazy.

Reply on news.ycombinator.com