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.
Twice in my career I’ve implemented a system to generate “good docs” from source. Twice I’ve failed. I’ve seen several other such initiatives which also failed. In every case, a more friendly editing experience won over the “check it in and type ‘make doc’” experience. That could have been MediaWiki, Confluence, Box notes. People even preferred the abomination that is Sharepoint over a source-based system.
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.
That's absolutely true: the golden rule of keeping docs with code assumes that the documentation is /about/ the code - class and function descriptions or web API documentation for example.
For product-level user-facing documentation written by non-engineers I think it's entirely appropriate to use a different tool.
> 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.
"product-level user-facing documentation written by non-engineers" is at one end of the spectrum, and clearly wants to use a different tool (eg Adobe InDesign) with code comments written by engineers at the other. Problem is, how do you navigate everything else that's in-between, while minimizing strife from one side making demands (some reasonable, others not) to the other.
I think most documentation at a company can and should live outside of version control repositories - the key thing is to have editing tools that non-engineers can use and to ensure that the resulting material can be effectively published, searched and made visible to the people who need access to it.
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.
Absolutely agree. The documentation relating to the code needs to live with that code.
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!
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.
I think you're leaning too heavily on your own personal experience. You're stating things as absolutes that are very much relative depending on the context. The world of documentation is much broader than your definitions.
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.