> I lost track of the amount of times I was told to "look at the source code" when asking about documentation for the internal framework.

Can you elaborate on this one? This is my preferred way.

You prefer just being handed a pile of code, rather than documentation on how to use it? please.

In case where I work for a given company and it's internal tool, always.

Imagine this scenario.

You work on product A. Your VP of very important things declares that every product should use library L. Library L has been designed to incestously interact with product D and makes a bunch of assumptions about what the "working environment" should be.

Teams B and C have already made the transition, so L made some kludgy APIs to make B and C interaction possible, though it is maintained with low priority because everybody knows D is the money maker. Both B and C have a bunch of assumptions in common that A does not share, and they both had to compromise and emulate D environment to some exent.

You are given L binaries, a few toy examples of how to use the most basic functionality in L, and access to B codebase. L codebase does not use the same source control system, so you don't even know where to begin looking for their code.

Please keep in mind that your manager does not expect you to learn all the inner workings of L. Your priority task is to use L to support some new feature in A. You still have a number of other tasks to accomplish in A that are not related to L, and some of those might raise in priority with little or no notice.

Do you still think it is a good idea to just browse L code, without knowing how large (or well writen) it is?

Note that I said it's my preferred way but by any means that doesn't mean that if there is some documentation I won't look at it.

The fact that it is your preferred way tells me that the only internal frameworks you have encountered in your career were tidy, tiny, and self contained.

Having struggled with very large tools that were anything-but, I beg to differ... but I guess it is a matter of personal experiences.

At best this is nonsensical, at worst, you're trolling all of us.

Instead of being able to quickly peruse docs to see if a method existed and what it took/returned, I would be directed to dig through source code to see if it exists and what it did. This is basic API doc work. This meant something that should have been fairly quick took significantly longer.

Then there were times when I did dig through to understand why something worked. When I pointed out that something should be done differently (an id-lookup done hierarchal instead of flat) I was told "Oh that's deprecated, you're not supposed to be using that anyways". And how exactly am I supposed to know that?

Ultimately it was a frustrating way to spend a lot of time.

Exactly. You can write it down once or have people figure it out independently many times over. Documentation saves engineering time.

Proper documentation that explains what the code should do, how it does it, and if there are any known bugs is a lot faster (IMO) to read them to open a file to try and parse what the people who worked on it intended and what all its doing.

Add in cases where people go crazy with inheritance and you need it or else you have no way of knowing what all it is this new class can do.

You seem to work at a horrible place, with abrasive characters.

It begins with the fact that the company's code needs documentation. I'm a big proponent of Robert C. Martin's "Clean Code" and the idea that code should read like prose - by reading the code, its purpose and ideas should come across naturally.

It ends with people asking "Didn't we already talk about this?".

Is this your first job? Don't let yourself get treated like this.

> You seem to work at a horrible place, with abrasive characters.

Or a normal place with poor-mediocre leadership.

Documentation doesn't happen by magic, and documentation is a skill. If it's not a priority from management, folks will be heads down getting their own tasks done, not thinking about what the other person/team needs.

I worked at a place with remote and onsite employees, and I think two of major reasons it worked is because we had a habit of documenting all designs and projects in a wiki, and used Skype at all of our meetings (while sending an invite out before hand to anyone tangentially related so they could sit in if they felt the need to). The wiki would inevitably get out of date, but it usually gave you a good big picture and the edit history let you know who to track down for questions.

All of the development teams were also on Slack, and many people tended to have those quick side conversations online instead of in person, so there was a public searchable record and you could jump in more easily.

To be fair, this happens in dysfunctional organizations that are all on-site, too. There's no good excuse for being that disorganized, but it happens all too often.