I have managed a lot of code, a lot of projects/products, and a lot of documentation. Code is code. Documentation is not code. The more you try to force Documen

I have managed a lot of code, a lot of projects/products, and a lot of documentation. Code is code. Documentation is not code. The more you try to force Documentation to be Code, the worse it is as Documentation; the more you force Code to be like Documentation, the worse it is as either. First, consider their purposes. Code is designed to be a set of instructions. It is designed to tell a computer what to do. It is a loosely structured, line-by-line organization of text. Documentation is designed to explain to human beings how and why something does or doesn't work. It is designed to give humans deep knowledge about a subject. It is an array of media and document types, structures, and features designed to facilitate humans composing and presenting information in an optimal way for humans to understand. Next, consider their usage. Code is designed to be interacted with via version-control system, used by build tools, in order to generate programs. Its access is highly controlled and often requires skilled labor. It is updated through a highly structured lifecycle. Documentation is designed to be interacted with by humans in a web browser or rich text editor in order to find, compose, and publish complex documents. It is designed to be accessible by all users, easily and frequently updated, by people who are not technical writers. It is updated in small pieces by anyone at any time without much regard, because almost any change is an improvement that does not require great scrutiny or validation. At the end of the day, developers just don't know how to make good docs. They think GitHub makes a good place for docs, when it's actually incredibly painful to create and maintain docs there for any reasonable human that needs more than a plain-text file maintained via an arduous SDLC or overly-complicated automated program. In fact, real documentation requires a system designed for documentation, such as Confluence or another Wiki, that has a WYSIWYG editor, mixed media, and enough editing controls to compose a rich-text document that can express complex ideas in minimal space using a variety of presentation methods. Markdown files are the perfect example of why Documentation is quite complicated to make. Markdown has only a small number of formatting features, and anything past them requires hand-written HTML/CSS. Trying to create a complex structure like a table is painful (if not unworkable) unless it's incredibly simplistic and small. It doesn't even natively support the most basic and universal feature of all documentation: a table of contents. If you want to document architecture, a DAG / flow chart, a comparison of tools, a series of products and what features they support, in-line snapshots of UX, etc, it's very painful (if not impossible) to compose such a document in plain-old Markdown. But I can throw such a document together in Confluence in 10 minutes, and actually make it easy to both read and navigate. On top of that, anyone can find, access and edit it without special permissions or knowlege, and reverting changes is dead simple. Now, is it useful to generate documentation of code? Absolutely! With Doxygen it's been trivial for ages to have a rudimentary reference for all of your code. But this is not the same thing as the "Documentation" that most projects need, yet is always conspicuously lacking. Those docs are often more project-specific than code-specific and can't be generated automatically, because they are complex, subtle, and touch on many things at once.