[bgaluszka]

> 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.

[overcast]

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

[bgaluszka]

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

[crpatino]

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?

[bgaluszka]

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.

[crpatino]

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.

[overcast]

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

[dandersh]

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.

[lallysingh]

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

[wazanator]

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.