This is essential. If developers have to hunt down the documentation it will never be updated. It needs to be generated from plain text files in the same repository.
Way to many times have I encountered documentation fragmented and outdated split between Confluence, Google Docs, Google Sites, GitHub wikis, network shares, Dropbox, Google Drive, separate git repositories, and other such abominations (MS SharePoint).
Treat you docs like code, treat it like it's important, it is the least you can do to even have a chance of producing marginally acceptable documentation, let alone good documentation.
If your docs are only written by developers, you might have a chance to make it work. If you need docs to be also written/edited by non-devs, I think you’re looking at an uphill path to get everyone into source control-based docs.
For product-level user-facing documentation written by non-engineers I think it's entirely appropriate to use a different tool.
I fantasize about an environment where a GUI's internals and interfaces are annotated sufficiently to discretely call from unit and integration tests, and version-controlled instances of those are linked to non-technical task management, user documentation, support tickets, support knowledge bases, patch configuration management, and so on. In this fantasy, if code changes a GUI element enough to alter its appearance or fail a unit test of the GUI, it automatically triggers a re-imaging of snapshots for it in all downstream linked documentation references and issues PR's for human intervention reviews of the new images (with adjustable cropping for finalized approvals).
That's my holy grail of single-source documentation.
Where do your business critical spreadsheets go?
The exception is engineering documentation: API docs should absolutely be version-controlled in the same place as the code they are describing.
I built an internal search engine for a past employer that covered 11 different sources of documentation - Confluence, Google Docs, GitHub Markdown, Salesforce Support and more - and it really helped solve some of the discoverability problems we were having.
The single biggest problem I see with documentation is lack of trust: if people in an organization learn that the documentation is often out-of-date they will stop consulting it, which means the will also stop writing it.
The fix for this is for the documentation to live alongside the code, and for code reviews to take that into account: if an implementation change leaves the documentation out-of-date, point that out in the code review and refuse to merge it until the documentation has been updated as part of the same change!
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.
I've been using a similar approach for my projects for a few years now and it's worked really well: I call it "Documentation unit tests": https://simonwillison.net/2018/Jul/28/documentation-unit-tes...
The tricky thing about A is actually figuring out the common use cases and then finding the phrasing that your users would say. I was lucky when I worked on the Chrome DevTools docs because I had a huge record of the problems that people actually faced and how they described them: all the google-chrome-devtools questions  on Stack Overflow. For smaller products where obviously you won't have an active Stack Oveflow community, a good source of insight is support tickets.
I don't really understand this. If the documentation doesn't exist next to the code it documents, isn't there a risk that someone will change the code without updating the docs, leading to confusing or wrong docs?
I'm beyond livid that Firefox Developer Edition stopped allowing me to paste "jar:" protocol URLs even though it still loads the existing ones I bookmarked just fine
* When documenting API’s, make sure to document preconditions and postconditions, as well an invariants.
* Make sure to document guarantees and non-guarantees. Guarantees are things the code must or must not do, where non-guarantees are things that give the code wiggle room and which users cannot rely on, even if they begin to, a la https://xkcd.com/1172/.
* Make sure docs can be tested, just like code. Daniel actually does this for curl docs (later in the post), but he does not list it as a standard. I think it’s a great way to help keep docs up to a high standard.