Programmer and mathematician. Problem solver. Lover of clean code, coffee, cycling, running and Italian food.
Kotlin, Java, Spock (Groovy), PHP, Angular, MariaDB, ...
As soon as developers are the target audience of the documentation, I have found that docs written in a wiki, Confluence or other external documentation tool always become outdated. And not in a year but rather one or a few weeks. Either it takes a lot of effort to update the docs or nobody will read them anymore.
Documentation in code solves this. A search for a code term also shows documentation. Whenever you open a source file with docs, it it easy to (also) update them in a PR. There are many tools for most languages to (auto) process docs to HTML or PDF form for distribution. And most importantly, the meaning/context/design of a model is clear the moment you read the code.
Of course, some documents are more drafts and should not be included in code. But even drafts and design documents can be included and removed/updated later. Especially because many documents are written in markdown so can be embedded in the relevant source file (often a model or root aggregate of a model).
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I really miss 'code' here.
As soon as developers are the target audience of the documentation, I have found that docs written in a wiki, Confluence or other external documentation tool always become outdated. And not in a year but rather one or a few weeks. Either it takes a lot of effort to update the docs or nobody will read them anymore.
Documentation in code solves this. A search for a code term also shows documentation. Whenever you open a source file with docs, it it easy to (also) update them in a PR. There are many tools for most languages to (auto) process docs to HTML or PDF form for distribution. And most importantly, the meaning/context/design of a model is clear the moment you read the code.
Of course, some documents are more drafts and should not be included in code. But even drafts and design documents can be included and removed/updated later. Especially because many documents are written in markdown so can be embedded in the relevant source file (often a model or root aggregate of a model).