Deeply specific, undocumented framework

Question

I have been working at this software company for almost a year now. They have written their own specific framework with custom types, structures and models. There is little to no documentation for it. The software team is basically 3 developers that have been here for 10+ years who know the framework mostly by heart.

I'm a junior employee with 1-3 years of experience. I am supposed to be getting up to speed with this framework. The framework is huge and so far it has been almost impossible to develop anything independently aside from minor things. I have been meeting with one of the developers to try and learn from them, but it's not going nearly as fast as I think it should.

I have brought up the documentation issue with the manager, and although he agrees, the 3 people that could document the framework are always busy with projects that bring in money.

Is this common? What can I do about it? Is the only way out looking for another job? How long is long enough to jump ship?

Answer 1

During several internships and my first job I had the same issue in 3 differents companies. So yes this is fairly common.

What you can do is while you learn how everything works write it in word or even txt documents so you will have a basic documentation which you can always refer to or if someone new arrive in the company you can give it to him and he will complete it with what he thinks is missing.

This can help having a first documentation....

Answer 2

The other answers seem to be taking the view point that a "deeply specific, undocumented framework" is 1) problematic, 2) needs to be changed and 3) you should do something about. I would suggest first identifying whether there is a problem at all, and if so what this problem is.

They have written their own specific framework with custom types, structures and models.

This could be because this framework permits the developers in the company to implement the company's products/solutions effectively and efficiently. Or it could be a case of Not Invented Here.

You haven't provided any information to tell which of these is the reality.

There is little to no documentation for it.

I expect that most software that is not used by other developers, including the vast majority of corporate software, does not have documentation. So, alone this is not surprising at all.

The software team is basically 3 developers that have been here for 10+ years who know the framework mostly by heart.

Are they producing software and solutions that work? Are they doing so efficiently?

I'm a junior employee with 1-3 years of experience. I am supposed to be getting up to speed with this framework.

I agree that this can be challenging.

The framework is huge and so far it has been almost impossible to develop anything independently aside from minor things.

"Huge" and "not independently" don't necessarily go together. A framework that has many interdependencies is often difficult to develop in for a newcomer, because you have to understand the whole thing to not break something. A project that is well-organized with fundamental CS principles like single responsibility, encapsulation, defined interface boundaries can totally be worked on relatively "independently", you'll just be operating in one particular subsystem.

I have been meeting with one of the developers to try and learn from them, but it's not going nearly as fast as I think it should.

You may need to adjust your expectations. In large systems it takes months or years to onboard completely. If you are used to small projects or start-up companies it is a very different experience to have worked for a big company for, say, 6 months and still feel like you don't know that much. This is normal in large companies.

So, instead of going by your idea of how fast you should be ramping up, ask your boss (or even one of the other developers that you are most friendly with, how well they think you are picking up the system).

Remember: by your own admission, they took 10 years to get to their present state.

I have brought up the documentation issue with the manager, and although he agrees, the 3 people that could document the framework are always busy with projects that bring in money.

This is also normal. You are unlikely to succeed in getting the system documented. You can succeed in learning it, or you may find that your brain doesn't work in that particular language/architecture/coding style. I, for example, generally do not enjoy looking at Java code even if the library/program in question is smaller than a large Ruby framework I have no problem with.

What can I do about it?

First, and most important:

Talk to your boss about what is expected of you and whether you are meeting the expectations. If your boss is perceptive they may figure out that you need some words of encouragement and provide those, assuming you are in fact meeting expectations.

Then, formulate the problem. Are you unhappy with your onboarding speed? Do you not like the architecture of the system? Do you feel you are not receiving enough support?

Depending on what you perceive the problem to be, the course of action will vary.

Final note:

You say the other developers are generating income for the company. This means every day they need to decide whether to generate income or train you. Depending on the company's priorities, they may be prioritizing generating income and not allocating much time to your onboarding.

This may be factored into the expectations that your boss has for you.

Regardless, this isn't the best place to be because a company needs its employees to generate revenue. To fix this, I suggest taking initiative but not in demanding documentation but in working on whatever you think will help the company generate revenue. Try to come with a way how you can do something that would translate to dollars earned. You need to formulate this in a way that is clearly beneficial to the company in terms of the bottom line ($$$ earned greater than $$$ spent on helping you). This will incentivize your boss and through them the other developers to allocate more time to you.

Answer 3

Unfortunately this is quite common. There are some things you can do to help.

Firstly I suggest keeping a journal of questions you have. Often just writing out the questions will help you find the answers yourself, but if you don't you can then raise them with your contact.

As you learn about the framework write your own documentation for it. Doesn't have to be too formal. When you have documented a section you can ask your colleagues to look over it to check that it is correct, and eventually the company will have some documentation for this apparently important bit of software.

Do they use any kind of documentation generation system where documentation is written into the code itself? If so improving it and submitting patches/pull requests is a great way to get familiar, get your understanding checked and contribute something useful.

Make sure your boss is aware that there is a steep learning curve but that you are making an effort to get up to speed while being productive.

Answer 4

This is sadly more common than you'd like it to be.

I've had experiences with several companies that had a similar environment. The main cause was always that management (who are non-developers) micromanaged the workload of their developers and took no care to dedicate time towards non-billables such as refactoring or documentation (whether because they flatout denied its importance or their developers lacked the good practice experience or backbone to ask for time to do it)

I have brought up the documentation issue with the manager, and although he agrees, the 3 people that could document the framework are always busy with projects that bring in money.

"We'll do it someday, when we have time" is more often said than done. In every instance I've seen, the same people never made time, and if time was made, would still find other ways to fill it. Don't believe an empty promise, especially if it has been made several times without any real action taken.

Unless you can sway the right people (management, or a sufficient majority of the developers who in turn can force management to listen), there's not much you're going to be able to do about this environment without singlehandedly taking on a herculean task.

What you do from here is up to you.

• You could simply fall in line and do the work in the way you can do it. If that requires constant assistance from the experts, so be it. It's the company's responsibility to provide resources so you can work with their framework. In absence of documentation or clear code, that means having access to experts to ask questions to. If they are not available either (or complain about your questions), point out that you cannot perform your duties until the issues are resolved.
• You could jump ship as soon as possible if you don't like this environment and would rather look for another company. Beware that there's always a chance of ending up in a similar situation, and you usually don't figure this out during the interview stage (unless they are blatantly explicit about their practices)
• You could see this as an opportunity to fill a much needed role in the company. Document the process, improve the good practice, take charge of creating a better practice environment. If done right, it can significantly improve your position in the development team. But it's an uphill battle when the rest of the team isn't on board.
• You can try to convince the decision makers to realize the flaws in the development process. Whether through discussion or solid evidence, you can convince people that they can improve their productivity if they improve their process. But beware those who have no interest in doing things differently ("but that's how things are done around here").

In my experiences, I gave each of those projects between 3 to 6 months of genuine effort and requests to improve the development process. In one case I managed to turn it around. In other cases, it eventually ended up in conflict with management who refused to listen to reason even when several independent contractors all pointed out the same issues, instead resorting to blaming those people for being unskilled. Toxic environments exist and some of them will kill you before you manage to clean them.

Whether you want to fight that uphill battle or not is your decision.

Answer 5

Well, it depends on how you want to approach the situation and how much management support you have and how easily/difficult it is to switch to a standard framework for what you're doing.

I mean, at it's most basic, you have 3 options:

• Leave.
• Learn the new framework.
• Convince your boss to allow you to start standardizing new development in a regular framework.

To be honest, I'd push for Option 3. And you should have management support on it. If it helps, bring up the point of: what happens when those 3 dudes leave? If your homebrew framework was small and easily learned, it might be one thing. But you're having a heck of a time doing anything other than just small changes. If those '3 dudes' left, would your company survive?

The most important thing to keep in mind is: you have to have a path forward. Management doesn't want to hear, "We're doing XYZ and it's going to destroy us!"

They want to hear, "Well, we're doing XYZ, but that's not going to work long-term. So instead, we should immediately start Small Change A, then do B for each new project that comes up, followed by C." In other words, a plan with as little pain as possible.

Answer 6

Like many other answerers, I've been in exactly the same situation, so I understand the downsides of it well. However, I'm actually going to try to emphasise some of the upsides of this situation - mostly under the umbrella of learning.

Let's be plain, you're early in your career so the likelihood is you'd be changing jobs before too long regardless - be it for this reason or a whole host of others. My advice would be to reframe your perspective on this from a reason to leave, to an opportunity to learn from whilst you're still there.

I think to best see the learning opportunities presented by working with a custom in-house framework, we have to step back to what a framework is. Basically, an abstraction over a lot of common problems in building an application that you can leverage to focus more of your energy on the parts of the application that make your product/business special, and less on the commodity pieces that most products/businesses have to implement.

That's of course why most companies use off-the-shelf frameworks. 99% of the time, those commodity parts really are all they need. The first thing to try to learn then, when a custom framework is chosen by your company, is why. It's pretty easy to hand-wave this as incompetence, and maybe sometimes to some extent it is, but probably more often the true reason is that the commodity parts provided by popular frameworks (at least at the time the application was first written) weren't adequate for the application, and the business problem it's solving.

Which parts, and why, is a really interesting question you're going to learn a lot from - whether they were right or wrong in their choices! (Learn what to do, sure, but also learn what not to do). At the end of the day, this is the essence of the job of a software engineer - coming up with, or at least mapping, appropriate technical solutions to business problems. The extent to which you're a good engineer more or less is the extent to which you can do that well, and learning how and why other more experienced engineers in your company chose to solve the specific business problems of your company with custom solutions that are fully open to you (as in, literally, you have the code in front of you) is a golden learning opportunity that is only available right now, in this job. Take it.

Outside of the more business problem solving perspective, from a purely technical perspective there's also a golden learning opportunity here. That is, that you're forced into a situation where you have to deeply understand and in some cases even reverse-engineer the custom solutions to common application engineering problems that in other, widely used popular frameworks, are just solved for you and handed to you on a plate.

In engineering, most learning is directed by necessity. You get to deeply think about and understand problems and solutions because you must. When they're solved for you, you might investigate how they work under the hood out of interest, but generally you won't go into as much depth or spend as much time on it as you otherwise would if you really had to to get work done.

Having to implement a framework yourself from scratch, or reverse someone else's attempt as in your case, is as I say a further golden learning opportunity to really understand the details of the problems that are being solved, which will be really beneficial for the rest of your career. The fact that you're getting to do this as a junior engineer is especially great. Again, yes it's perhaps not the most enjoyable thing and can be downright frustrating at times, I get it, but take advantage of this opportunity whilst you have it!

Answer 7

You are early in your career and it is normal that you have not yet experienced large projects, so you do not know what to expect when working with legacy code. You are specifically looking for documentation as this is how you would work with a large popular open-source framework (like Qt in C++, or pick an example from your core language).

This is not how things work in internal legacy code and it will make your future professional life easier if you learn how to find your way around a large undocumented code base, how to get help from internal experts without alienating them and how to write self-documenting code with a minimal need of the duplicate effort in documentation.

My advice would be:

• Reset your expectations. Do not expect that reading documentation will be the primary way to learn legacy code.
• Discover other ways to learn an existing project. There are some resources on the net for that, you can start with this question. As many things, this gets better with practice. For me personally, refactoring code gives the most learning per coding minute, even when I would throw this refactoring away later.
• You can often find an answer to "how do I do this" in some existing code which uses this functionality. Do not be shy to start by copying it.

Overall, there are lots of good reasons to run away from a project or a company. A large internal framework with insufficient documentation by itself does not strike me as a strong reason to leave.

Answer 8

I think a lot of things have been said already, but i'd like to give you some timespans from experience so you have a better idea about what to expect;

I interned at the company i now work for, straight out of school. During the hiring process they literally gave me a set of milestones (in a slightly humorous manner although they were all based on reality):

• 1 day before leaving, the shortest someone worked and left
• 2 weeks before leaving, as was most common
• 4 months, as that was mostly when employees stood with the company till old age.
• 4 months for both juniors and seniors to learn and understand the software

I majored in technical software engineering (C/C++, embedded systems etc) and wanted to move to full on software engineering (C#, web, desktop apps etc) so i barely knew basic constructs like OOP or the languages i was working with.

It took me half a year to feel like i was contributing at least something and a full year to finally felt competent enough to work with the software. It took me another half a year to feel like my colleagues' match on a technical level, and before i felt competent in being able to touch every line of software.

The whole situation was the same, no documentation (although the code itself was maintained pretty well), and nobody held my hand - and i did not even know the tech stack.

My point here is that it takes time and that you should not feel anxious about the time to come. Relax - I came out alright and so will you.

Some other tips i picked up along the way:

• Don't be afraid to break things down. Fear kept me back a long time, and to live is to learn.
• When you do eventually break things - make sure you have the right reason for doing it and make sure that you voice that.