[mtlmtlmtlmtl]

The code is the best manual you'll every get in my experience. There's no substitute when working on a codebase.

When I'm introduced to a codebase I'll be doing significant work on, I'll often spend hours at a time just reading the code. Start at main() and skim until you get a feel for the overall architecture, then go figure out whatever subsystems seem mysterious to you. Rinse and repeat. Makes a huge difference when making changes, because that requires reading code anyway, and you'll have a much better idea of what code to read/change.

[adave]

Imo reading gets you nowhere and is inefficient. Key piece is to add some form of self explanation or diagram to map the overall picture, since it takes a lot of repetition to understand the code flow but only hours to come up with a data flow diagram and revisit/update when needed. Even faster when someone on the team has already done it.

Maybe its just me but plain text does nothing for me so i convert it into visual elements.

[tstrimple]

Code also has the advantage of not getting out of date with what the application actually does. Invariably, documentation outside the code base often rots over time until it reaches a point it's outright misleading.

[rahimnathwani]

Yup, that's a good reason to keep documentation in the same repo, and to update documentation in the same commit as the code that causes the change.

[noisy_boy]

One scenario where I find external wikis better is when a change encompasses multiple components and you want to present an overarching view to the user + want to refer across sections. This can be managed via something like github pages for each component but the cross referring across multiple repos adds more friction. Plus to present the overall view, something like a synthetic "doc-repo" will be needed that has landing pages that connect the component-level pages. Or we can have a wiki that does the integration by refering to component level github pages but at that point why not just do the whole thing in wiki much more conveniently.

My experience is that it basically comes down to developer discipline. A disciplined developer will update the docs regardless of whether the docs are part of repo or external and vice versa.

[jen20]

> Start at main() and skim until you get a feel for the overall architecture

Man I wish that worked for Java ;-)

[sigha887]

And it will for all future make it impossible for you to distinguish official API and implementation details.

[mtlmtlmtlmtl]

That just comes with the territory of being someone who has to understand the implementation details. No getting away from that.