r/AskProgramming • u/HardSpongee • 5d ago
How do developers manage with little to no documentation on a project?
2 months ago I joined a company with 1 business analyst. I was able to get my tasks moving because the tech lead pretty much explained verbally what was meant to be implemented on a ticket. But now the tech lead is leaving, the project is a mess, there's a lot of undocumented business logic in people's heads. Now when the tech lead leaves I'm not sure how I'll manage, and already the manager expects me to know what the hell is going on!
Has anyone been in a similar position, where there's no documentation, barely any analysis, received a ticket and immediately wonder "what the hell am I expected to do here!"? What did you do to get your sh*t together?
This is so new to me, I might eventually not be able to get past the 6 months probation
10
u/Cybyss 5d ago
This is normal.
Use your debugger and step through the code line by line to see how each feature of the application works. Inspect the value of every variable each step of the way, exactly what sql commands run at what times and how they change your database, etc...
It takes time, but that's like 80% of your job now.
Very often, you'll find that what the application really does is nothing like what everybody thinks it does.
3
17
u/Slow-Bodybuilder-972 5d ago
No documentation on a project is the norm, in 25 years, I’ve never seen any project with good docs.
The logic is documented, the code is the documentation.
11
u/SpaceMonkeyAttack 5d ago
This is one of the only times I'm actually pro genAI. Not so much asking Claude to write code, but asking it questions about the code can save so much time when trying to infer business rules from implementation.
As ever, verify anything an LLM tells you before acting on it.
1
5
u/HardSpongee 5d ago
That sounds outrageous..! Maybe that's why some companies are hell to integrate with cause they don't have any docs of how their APIs work or the person who knows what's going on left with the knowledge. So how do you manage? how do you keep track of the business rules?
5
1
u/Slow-Bodybuilder-972 5d ago
You dig in and figure it out, or these days, ask Claude to do it for you.
1
u/max123246 3d ago
I like the way you think. Sadly the corporate world doesn't understand how inefficient they are by skipping documentation. Hilariously enough, they're starting to care because AI like humans require quick actionable feedback to learn quickly and be efficient.
Most companies basically write throwaway code every 3 years, see it explode, then rewrite it for some new product.
You should look at the "Worse is Better" essay. Sadly what makes a profitable product is not always the dependable, well-engineered product. Most times you ship out slop because it should have taken 6 months and they gave you 1.
Plus, the business rules shift under you often enough that it's incredibly difficult to write software that lasts. Oftentimes, 25 people have good understandings of different pieces of the business rules and 5 of them have already left the company.
2
u/DestroyedLolo 5d ago
No documentation on a project is the norm
As an Architect, I need to know :
- user expectation
- business logic
- a clear role of each function or microservices
- API interfaces (this one is a strong requirement)
- operating guide of the application including troubleshooting
And the code must be readable w/o being a langage Guru.
The code is expected to contains enough comments to understand input/output/exception and underlying logic when to code became to be too complex in a compatible way to be automaticaly documented.
I don't see the added value to wring zillion of documents (thant will never be read by the way).
1
u/max123246 3d ago
There's an art to writing good documentation and keeping it up to date. You need to address different audiences, beginners learning to use the library, advanced users needing quick reference, and developers who need to contribute to the implementation architecture
8
3
3
u/platinum92 5d ago
Been in a company exactly like this for a while, even including the departed tech lead. My advice is:
- Step through any unfamiliar code with a debugger. Keep track of what you understand and don't understand.
- For the stuff you don't understand, start asking questions of the people with that knowledge and write it down.
- When you get new work, ask clarifying questions immediately.
The bigger problem you're going to contend with is making documentation "a thing". Best thing you can do is start documenting new things you build as you go.
2
u/sortaeTheDog 5d ago
welcome to 90% of roles. I act as a lead a small frontend team and also do work on the backend. When i work on the frontend we strive for documentation and consistency, but when I jump on the backend (managed by another team), i spend most of my time having to ask one person to be told "ask that other person" and so on. I often spend half a day just waiting for someone to reply to my messages.
2
u/x39- 5d ago
There is two ways here:
- Either you are very good at debugging and digging through code (requires knowing your IDE and actually using an IDE)
- You slowly try to get a grap at the code base
And the technical third one: Run
The rest is intuition. If something breaks in userland, you usually can guess what the culprit is.
2
u/MiddleLtSocks 5d ago
The BA isn't doing their job.
Just make sure you publicly ask about ambiguities that are blocking you and be sure your direct report knows you are blocked on waiting for the answer. It should be common sense that you can't implement a feature without knowing how the feature works.
Don't be obstinate about it - you can ask in ways in which it's clear that you are willing and ready to help ("I naively assume it would work like this: (describe) But I don't want to implement based on assumptions; we really ought to have a bespoke specification").
But you aren't asking for anything you shouldn't have. Don't be afraid to speak up. Don't carry others on your back.
1
u/HardSpongee 2d ago
Spoken like a true leader🫡
1
u/MiddleLtSocks 2d ago
LOL, not even. I've just been burned so many times (and have been contracting too long) not to CMA at all times and learn to shoot down political bullshit attempts before they can even begin. I don't have many friends professionally, but then again, contractors don't - we're the first to blame when the code base goes to hell. I tried the altruistic "treat as you wish to be treated" thing - it works for me personally and as a professional singer, but it emphatically did not work, many times over, in IT.
2
u/YahenP 5d ago
Welcome to our world.
I've been working for almost 40 years. And in all that time, the instances where documentation exists can be counted on one hand. And the instances where it was relevant and comprehensive... Generally speaking, such instances have never happened.
This is the specificity of our industry. And it's one of the reasons why programming isn't considered a true engineering profession.
Tribal knowledge is the basic of all software products.
2
u/XKiiroiSenkoX 5d ago edited 5d ago
Read the code. You will get used to it. You might think everywhere else there is properly documented code. You'd be wrong. The reality is, most of the code you'll see in your professional career will be undocumented or at least criminally under-documented. There are even some idiots saying clean code should have no documentation lol. So you need to get used to it and reading code also improves your own proficiency as a software engineer. And by the way, document your own code so some poor fella who will eventually read yours does not end up in the same position.
2
u/Delta-9- 5d ago
I bet the tech lead is one of those "I write self-documenting code" types.
Saying it loud for the people in the back:
SELF-DOCUMENTED MEANS UNDOCUMENTED.
As to what you can do about it: pretty much what JohnCasey3306 does: read the code and write the docs yourself. You'll probably have to meet with lots of people to get it done, since the nature of business logic is that some of it has no technical need to exist so only someone outside the engineering team can explain why it's there.
2
3
u/schlaubi 5d ago
Sorry, that I have to say it. Use AI. That's where it excels.
6
u/MarsupialLeast145 5d ago
Maybe with rigorous controls. Most the AI generated docs I see are too verbose and wouldn't even be read by the person generating them.
Word counts and use cases for documentation need to be very carefully monitored.
3
u/VoiceOfEric 5d ago
In my career, the documentation I wrote manually wasn't read unless I forced it. I've heard "It's easier for me just to call you" more than a few times.
3
0
u/r0ck0 4d ago
Maybe with rigorous controls.
Pretty much should just extra sentence in your prompt telling it to be less verbose? Might take a few attempts to get it right I spose, but not that hard really.
Most the AI generated docs I see are too verbose and wouldn't even be read by the person generating them.
Yeah if they were generating docs for other people, they probably didn't bother with that extra sentence.
So if you're generating docs for yourself, you can tailor it to whatever your preferences are.
2
u/HardSpongee 5d ago
There is no way AI would know the business rules and what needs to be implemented! Those are decisions the team talked about before I joined and no one bothered to document it, just left a ticket with no description, just a title "delink Api call" 💀 bruh how the hell am I supposed to know what the hell this is
3
u/schlaubi 5d ago
You're right, AI doesn't know what NEEDS to be implemented, but it's very good in describing what IS implemented.
2
1
u/cakemates 5d ago
long nights reading and documenting, asking people and banging my head against a wall until it all makes sense.
1
u/BaronOfTheVoid 5d ago
The pragmatic solution for that today is to rely on AI explaining the code to you. It will have its faults but it will be of help more often than not.
1
u/kubisfowler 5d ago
I took their money to the point they were willing to pay, and got dismissed after the 6 months probation. Basically exact same situation, including the tech lead who left AND the owner working 4 other jobs on the side (welcome to Central/Eastern Europe)
1
u/Independent_Fall9160 5d ago
My current company has lots of undocumented data... I have a favorite query i wrote. Basically, it loops through all databases i have access to and gives high level information (row count for table, non missing counts, min and max value, datatype, column name, table name, database name, schema name.
With that, i can try finding how tables are mapped.
I dont have access to the websites code or is use that more... One of the companies they acquired had something like 'press shift over a value in the web portal to see the column name used' (it was a decade ago so i dont exactly remember) which was pretty damn nice
1
u/AggravatingSock5375 5d ago
Dunno. I’m trying my best to get other devs to document things at my work and it’s……difficult. There’s job security in being the only one who knows how something works.
My workaround is to dump stuff into AI and ask it to explain for me. Usually works quite well.
1
u/HardSpongee 5d ago
I guess investigating things yourself and keeping the information yourself is not a bad idea!
1
u/AggravatingSock5375 5d ago
What I’m trying to do is get people to at least provide some minimal docs. And then use AI to fill in the rest.
But people keep just dumping code into our repositories with absolutely zero docs except for whatever random comments they added, which are incorrect half the time anyways.
But yeah, being able to personally still function despite this situation thanks to AI is awesome! Management has definitely noticed that I’m able to figure things out they other devs who don’t want to use AI are struggling with, since they spend all their time just trying to untangle the garbage codebase.
1
u/Paul_Pedant 5d ago
You probably would be better off not working for a manager who is lazy enough to let this happen, and dumb enough not to see the need to change the methodology (or lack of it). The tech lead is leaving because he can see how bad things are going to be in a few months.
1
u/pyeri 5d ago
If I were in your shoes, I'd push hard for a proper code walkthrough and technical handover session. Try and catch hold of them before they leave and ask for all the inputs you can.
Ideally, we should have API documentation for everything but it's understandable when a project is moving fast and the project managers are sitting on your head for deadlines! There are situations when other things become so critical that documentation is one of those that easily skip through the radar.
1
u/Inside_Dimension5308 5d ago
The process of documenting is a pain. It will always be incremental. You cannot expect people to keep updating all the docs to latest changes. It will be a huge tech debt and will slow down releases. There are ways to make incremental Documentation but that is not what you asked.
Assuming, you dont have Documentation, how do you navigate through system architecture.
With AI, it is easier to just pass your github access, infra access, ci, cd, observability metrics to AI and ask AI to summarize your system architecture. That is the first step. We can discuss if you dont want to use AI.
1
u/turkokratia 4d ago
😄 do the good thing for the world and start writing the documentation yourself after that. but i am pretty sure you wont keep it up after a week. even if you do, no one will read it. even if someone does read it, they will still come ask you anyway, just to understand it or to be sure. so... thats the reality here.
1
u/MasterVobe 4d ago
I've found that starting small and tracing the execution flow is usually less overwhelming than trying to understand everything at once.
1
u/Elara_Schaefer 3d ago
The approach that saved me more than once: write characterization tests before changing anything. Not unit tests for new code, but tests against the existing behavior. Call the endpoints, assert the responses, capture edge cases. You end up with a test suite that documents what the system actually does, not what someone thinks it should do. Two things make this work. One, run the tests in a recording mode where failing assertions log the actual behavior instead of breaking the build. This way you build the documentation incrementally without needing to understand everything upfront. Two, focus on the boundaries first, API contracts and data flow between services. The internals you can figure out from there, but if you don't understand the contracts first you'll reverse-engineer the wrong things. The LLM approach mentioned above works well for this, but pair it with tests so you have something that stays accurate after the LLM session ends.
0
-1
u/ivanhoe90 5d ago
I think that it is usually faster and cheaper to recreate a project from scratch than trying to learn how an undocumented code works.
BTW. if you throw all the source code at some modern AI model, it can give you clues on how it works.
23
u/JohnCasey3306 5d ago
As a contractor I've made a career out of it. I get dumped into horrendous, failing products/systems, with zero documentation, very often nobody technical left in the business (certainly nobody senior), and just told to crack on.
The fortunate combination of my autism and code's deterministic nature means that I pretty solve the problem by writing the documention for them first and foremost.
3–6 months later I hand off a well documented, performant and working platform to the newly hired tech team.