Ask HN: How well maintained is the documentation in your company? | Hacker News Reader

Ask HN: How well maintained is the documentation in your company?

10 pointsGrimm16 comments

Writing documentation is hard and we all know it's not really incentivized to do it besides knowing that it will save us and team members headaches later on or stop a system from falling over when some poor eng has to take it over months or years later. I also know every boss I've ever had wanted documentation, or at the very least paid lip service to the idea.

I've only worked at one company now where the documentation was meticulous and not half done or just not done at all and I'm curious is this normal for everyone else or have I just been in some minima where this stuff doesn't happen?

View on HN

I've written >90% of the existing documentation as well as additional in-house tools to aid in my writing documentation that are themselves documented and shared in the documentation in hopes others will help write some of the documentation.

Every other tech loves and makes use of my documentation - it is one of the most referenced things in the company even by the techs who should be the ones writing the documentation for their code in the first place. Most of the existing documentation is documenting the undocumented features released by another tech department. I left the company for a year and when I returned there were only 3 new additions to the documentation, each one minor, and about 15~ new, undocumented features for our next iteration of our product. I've spent the last few weeks digging into the code and writing documentation for these new editions.

If I didn't care about documentation as much as I can't imagine there would be any documentation at all.

First, thank you. You sound like a very conscientious person. Second yeah that is generally what I've run into it's often one or a few people writing documentation that really benefits the organization but other people don't carry the weight and so when that person leaves it starts to harm the company as docs drift out of being current and no new docs are created, it is a slow burn though.

I wonder how we could reduce friction so more devs start to write code, that they clearly know they benefit from.

Start to write documentation*

I posted something related to your request earlier today: https://news.ycombinator.com/item?id=27157429 I would like to see more discussions around these documentation questions.

I think talking about documentation is important because it's really the key to helping people understand code, and therefore maintain it. I think the idea behind self documenting code is nice, you should write code that is easily understood, but it falls short of being useful for the broader organization on a few fronts.

I have found in longer existing organizations discoverability of the existing code is a lot more difficult than searching for the human readable documentation equivalent and when even that is not a problem there's no real consensus on what clear and simple code is but even if the documentation isn't written by a strong writer it's easier to understand the system still from that documentation than by code which may have been written in a similarly confusing manner.

Of course if no documentation exists, such as what I've experienced, my point is moot, but then other issues are sure to abound.

I've heard a story recently about one of the larger brokerages in the world back in 2008 almost not being able to repair their login and authentication systems and when they did it taking a significantly longer time because no one had documented the system and that's terrifying to think about.

Is it possible to write good comments while writing codes and there must be some sort of converter thats takes these comments and make a documentation

Reply on news.ycombinator.com