Comment by dano | Hacker News Reader

Comment by dano | Hacker News Reader

I looked at it this way. The thing most engineers, hero's or not, want to work on is new projects and to build products customers enjoy. The last thing they want to work on is maintenance. In my last personally owned company, small as we were, the engineering team and I documented how things worked as part of what we did every day. We found that by having the inner workings documented so that anyone in the team could effect a repair or update a piece of code freed us to work on new products and services. Just having the system continually documented freed our minds and kept us mostly happy (everyone has a challenge from time to time) and productive.

The documentation, not that it really matters, was done in a MoinMoin wiki. It was written by engineers, for engineers. We didn't stop marketing or sales or anyone else from reading it, but the target audience was the engineering and operation staff thus no one had to over-explain the vocabulary of our architecture.

> Just having the system continually documented

In my experience this is the hardest part. Can't count how many times my team started documenting and then slowly, for one or the other reason, the documentation became outdated.

The cycle is: Meetings for communication -> becomes too cumbersome and time consuming -> implement policy to document things -> everyone start documenting (for a month or two) -> docs are not up-to-date because people forget/leave etc.. -> go back to meetings

In my experience it's a culture thing. When I learned to love Jira/Confluence was when the product team conducted meetings directly from Jira and during task discussion almost always asked us if tasks and documentation were done.

It could have been really annoying but the product lead was extremely empathetic and that could be felt in any task discussion, and his attitude made me want to do it instead of making it feel like busy work like it has in other companies.

This is supposed to be enforced in code review or with other team practices / processes.

I must be weird. I love maintenance. The best bugs come out of that. And it's hard to tell if a system was well designed except in hindsight; maintenance programming is the best place to be for that.

You’re not alone. I may not love “maintenance”; but, I do love resolving performance issues and shoring and standardizing existing stuff a lot. I think I most like a balance.

I absolutely hate maintenance, so I love people like you. That is why its great to have a small but diverse team.

How did you get others to read the docs?

This is ~our approach, but it seemed to stop after ~150 employees or so.

(You also seem to have the time to write the docs…)

In my experience, documentation is the first thing to go when the workload increases. There are always tasks that get labelled as "important, but not urgent" that get pushed out; and documentation that is already known to everyone immediately involved is easy to push out beyond the product release date. Of course, by then other priorities are moved up, and documentation never recovers.

The only way I've seen documentation get the priority it needs is if management mandates it as part of the release package on which developers' performance evaluations are based.

How did you manage to keep the documentation from going stale or efforts being duplicated?

Reply on news.ycombinator.com