Software Documentation Debate

I'm sorry, but documentation is a waste of time. It is never complete, never up to date, never easy to find something in, etc.Spend the time to make whatever you are doing self describing. Write cleaner code, use infrastructure as code, ci/cd, automatic service overview, proper sprint planing, etc. Anything that improves everyones day to day life, even if they have all the information, experience, etc.

I’m going to relate an experience rather than answer your question. I don’t think the question is in its best form because it can be time consuming to write proper documentation. The existence of the “fairy godmother” takes time out of the equation which is an important variable.I used to work at Microsoft on a team with poor documentation. By my reckoning developers writing code would have preferred better documentation while developer managers couldn’t justify the time to write it. Both pre

"Linode’s technical writing team"This is the key. Someone has ownership over the docs. This is their job. If you expect programmers to invest into good docs, you need to measure them on it. Otherwise, you are hoping they write good docs. If you don't value the docs they write, they probably won't spend time on it. Like most people, they will put effort into what gets measured at performance review time.

Why do you feel documentation is pointless?

So tldr: people don't like writing documentation, and it's hard to make them care.

Hot take: The docs are an important part of the product. If you notice that the docs are bad, the product is bad.Docs are hard and thankless, but ¯\_(ツ)_/¯ them's the breaks.

No matter what you do, you have to solve what I call "The Documenter's Dilemma" or nothing will end up working long term.Let's presuppose an already-functioning documentation system, and three types of organizational players: the "Outstanding Engineer" (OE), the "Grinding-style Middle Manager" (GMM), and "GMM's middle or junior Engineering staff" (GES).Imagine the following scenario: OE, a true believer at this point, authors an outsta

Congrats on launching!I regularly spend time on developer documentation (just yesterday roughly two hours...). Unfortunately, your messaging does not resonate with me at all.Creating (good) documentation will never be easy, or hassle-free. We have to communicate/teach technical concepts to a wide range of developers, from beginners to experts, from native-speakers to I-barely-understand-english. Having a huge document with lot's of details is bad, because one can't grasp the

Documentation! It's the one thing no project does right. A google search and stack exchange answer from 5 years ago is no where near good enough.

Terrible experience for anyone who isn't already a contributor to that repo.Docs exist for people other than those that wrote them. The people that wrote them don't need to know the information, they already knew it.