28

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?

  • 26
    What you describe is fairly common for companies who had a product out for substantial amount of time. – Tymoteusz Paul Jul 13 at 14:28
  • 1
    we can't help you make decision to "jump the ship". What is the problem you are trying to solve? Are you unhappy about something? There are always troubles in workplace that slow you down, you have to choose what you value – aaaaa says reinstate Monica Jul 13 at 15:03
  • 11
    to follow on from @JoeStrazzere, ask if you can install a wiki somewhere, every question you ask, write down the question, followed by the answer you were given., if your using email or slack, cut and past and tidy up the copy. Also it may be of value for you to add comments directly to the code at the point where you questioned something and it was answered. especially in the clients of the framework, you never know over time you may become the go to guy for answers and any new hires will thank you – Ourjamie Jul 13 at 17:47
  • 7
    you are lucky, the people who developed the framework still work there. you must approach the framework a piece at time : ask to be assigned easier task first, to take confidence with it. Writing documentation is a good tip. – Stefano Jul 14 at 8:04
  • 2
    I'm a junior dev working with a big open source alright documented framework for close to a year now. And I sometimes still feel lost. So you also have to take in account that there is a big learning curve when learning any new framework – SirDuckduck Jul 14 at 12:49
48

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

| improve this answer | |
  • 5
    I did the same when I started my current role. As I was getting to understand the framework, I wrote basic notes that formed the beginnings of the documentation. Then I got used to it and I became the old developer that didn't write docs anymore... – Fred Stark Jul 13 at 23:47
  • 2
    Yes, document as you go along and periodically send a link to the manager (not the document). S/he will thus know that you are working, not just struggling. Speed and skill at documentation is a great plus for a CV and for interviews. Everyone knows that this is something that is neglected - often with disastrous results - if the key person retires/leaves/dies. If you decide to leave and want a good reference, chat to the manager and say you hope your (incomplete)documentation will be useful for your successor(s), 1. to get up to speed, 2. as a structure in which to continue your good work. – chasly - supports Monica Jul 13 at 23:56
  • 2
    In my experience I've always done better getting people to do things if I bring along a strawman. Having some basic level of documentation that's written from your learnings as you go is more likely to get picked up and improved upon by the other developers, than if you just bring up "we should have better documentation". Invariably, I've found the latter to be met with "Yeah we should" followed by no change. Whereas bringing in even something basic has a much better chance of growing legs with the rest of the team. – Kialandei Jul 14 at 10:55
  • 1
    @FredStark "You either die a hero, or live long enough to see yourself become the villain" – bracco23 Jul 16 at 15:19
15

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.

| improve this answer | |
  • 5
    I broadly agree with this, but I think by "independently" the OP didn't mean "without touching other sections" but "without significant help". – user3067860 Jul 14 at 12:41
  • 1
    "This means every day they need to decide whether to generate income or train you." Good answer overall but this is surely the bosses job - they need to balance the competing demands of current projects, the income they are generating and the need to get you up to speed. – Alan Dev Jul 14 at 13:28
  • @AlanDev that's swell if the boss is appropriately technical, but he/she may have no idea of what's entailed in bringing a new hire up to speed, especially if he/she has only ever managed the 3 engineers that have been there for a decade and wrote it all themselves. As this answers says, it's really an issue of making sure that the expectations on the OP are both clear and reasonable. – Jared Smith Jul 14 at 14:12
  • Doesn't matter what skillset they have it is absolutely the managers job to resolve competing priorities. – Alan Dev Jul 18 at 9:28
11

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.

| improve this answer | |
  • +1 for this last paragraph especially. Presumably, the expectations for you as a junior will be lower than more senior devs. These lower expectations should give you time to both learn and document as you go. As OP mentioned, the people best equipped to document things are often ones who “are too busy” to do so. Don’t wait to document until you’re already in that situation – DongKy Jul 14 at 0:52
  • 3
    One big advantage of putting your documentation in the code is that the other devs will see it, and hopefully correct it when it's wrong. They'll never look at it otherwise. – Robin Bennett Jul 14 at 11:56
  • This is what README.md files next to the code in the git repository is for. – Thorbjørn Ravn Andersen Jul 14 at 13:48
5

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.

| improve this answer | |
  • "Document the process, improve the good practice..." Sadly, "uphill battle" may be a understatement. The problem is that if the other devs stick to their ways and update and add to the codebase without updating and adding to the docs, your documentation will be next to useless in no time. Doing it for them is not really an option in my experience. I would say: Get the others on board, if not, don't bother. – Douwe Jul 14 at 9:44
  • Same goes for every other best practice by the way. – Douwe Jul 14 at 9:46
  • @Douwe: Maybe I'm biased because I don't mind writing documentation and tend to end up maintaining the knowledge database in most cases anyway, so I don't mind fishing for a position that may end up with me writing more docs than code. – Flater Jul 14 at 9:57
  • 1
    That is an awesome mindset for a developer, but I suspect it is also quite rare. To me, writing the docs (and some forms of refactoring) are chores. I'll do them because they need to be done, but if I'm the only one that bothers my motivation will evaporate quickly. Anecdotally I would say that most developers I worked with are like that, although I am not aware of any study that proofs or disproves that assumption. – Douwe Jul 14 at 10:43
  • 1
    @Douwe: I don't like it either (else I would've become an analyst or technical writer), but my reasoning is that good practice requires people to do annoying chores for their future benefit. I'd rather do a more annoying chore and work in a good practice environment than avoiding the chore and having to deal with a bad practice environment. It's still selfish, but on the long term. – Flater Jul 14 at 11:15
2

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.

| improve this answer | |
  • "start standardizing new development in a regular framework" and throw away 10 years worth of investments? Unlikely to happen. If you would do this, you would be confronted with a situation where you will need to work both with the old and the new framework. And with little knowledge of the old framework, it will be hard to 1) suggest a replacement that fits the needs and 2) work on getting rid of the old framework. – Mark Rotteveel Jul 14 at 15:12
  • 1
    @MarkRotteveel - I disagree. I've done this successfully twice in my career with long-developed frameworks. Our current Content Management System has 23 years of "investment", but we're actively modernizing it. And we're doing it by making sure new development is done in a more modern framework, then looking for minimal effort ways to transition systems away from the legacy one. Also, watch out for Sunk Cost Fallacy: just because the company has put 10 years of effort into something doesn't mean it's automatically worth continuing instead of replacing. – Kevin Jul 14 at 16:04
  • 1
    Maybe it'll work out, but I'm skeptic that a newcomer to the field like the OP will be able to pull this off, and I guess chances are high that - if the current developers don't have issues with this framework - you won't be able to get buy-in to do this. – Mark Rotteveel Jul 14 at 17:03
  • @MarkRotteveel - that's a good point about newness to the job. I guess it might depend on what sort of 'framework' the OP is talking about. Something like a Unit Testing framework is simple ("We could just switch to XUnit!"), something more intricate that can't be serviced by an out-of-the-box solution... not so much. But I don't think it matters if the '3 dudes' don't have buy-in. The senior member of our group didn't have buy-in for the new CM system. The manager did. The senior member was told to simply maintain the existing system while the new system was architected. – Kevin Jul 14 at 18:00
2

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!

| improve this answer | |
2

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.

| improve this answer | |
1

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.
| improve this answer | |

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .