I work at a fairly large startup/company of about 1000 people, a fraction of which are software engineers. We have some docs of various kinds, but the codebase isn’t documented. Let me elaborate.

Here is what we do have.

• “Getting started with the codebase” guides (how to configure your new machine to run the code).
• External product walkthroughs (from a UI perspective, usually on the marketing site)
• Internal product roadmaps, notes, bug lists, todo lists, etc..
• Slack with lots of communication about code, product, etc..
• Storybook documentation of central reusable UI library (includes standard UI library components like tooltips, modals, etc., not product-specific stuff).
• Unit tests, integration tests.

But what we don’t have is:

• Documentation of the frontend codebase. We use TypeScript, so we have types, but they are not explained how they are used or what the various props mean, etc.. We have lots of modules of various types, but few if any code comments, except when things get particularly harry, complicated, or hacky and you need comments to explain wth is happening. So it’s hard to tell how to use what we have, let alone know what is even in the codebase, unless you read though the 10’s of thousands of modules/files in the codebase, which is impractical.
• Documentation of the backend codebase. Same situation here, but an even larger codebase.
• Documentation of the overall architecture of the company software products as a whole (so you can see how things are wired together). Stuff like devops, infra, etc… Subteams might have docs they put together for this or that, but there is not much in terms of cross-team global shared docs on all this stuff.

So I’m wondering what the practices are of large companies with lots of resources (Facebook, Google, Netflix, etc.), or even smaller companies but still considered a fairly decent size). How much codebase documentation do they have? When do they get around to creating it?

Some code is probably used by several subdivisions of the company (i.e. “central” code), so this likely won’t change every day. But other code is used by the “lef nodes” of the company, such as new products or divisions of the company, so might change and evolve rapidly. So I’d expect there to at least be documentation for the central code, but maybe not much for the leaf code.

For the central code, what I’d find most useful as a new employee is a high-level overview of what the main modules are, and how you might use them, with a few examples of usage. This would let me know what I don’t need to recreate, as well as what’s possible in the codebase.

Then as a second layer, it might be nice to have some rough API-level documentation on the frontend/backend, to show you examples of how you might write specific code. But I wouldn’t expect every single function and it’s interface to be well described and documented like you find in a popular open source project.

But what is it like in a bigger company? Please elaborate a little on what you have seen, so I can get a sense of what would be realistic to implement wherever others may work, when there is little code documentation when they start.