Hacker News Reader

Comment by giantg2 | Hacker News Reader

In my experience, the biggest obstacle in understanding the system is that the underlying business process is not properly documented. A technical system is only as good as the business system it's implementing. Knowing the business process makes it much easier to understand the technical implementation, especially if you're trying to find bugs in the technical system since you can more easily see the mismatch between business and technical processes.

But hey, that's just me. And it seems clear that most businesses do a poor job, or don't care at all, when it comes to documenting their processes. So I guess I'm the odd one.

View on HN

Heavily agree. So many times rewriting a feature from scratch is faster than figuring out from code, and there is a lot of really hard to understand code out there.

I remember once in a consultancy job for a bank having to maintain a form with a file uploader made of dozens and dozens redux actions interwhining in the most complex way one could imagine. There were atleast 4 folders of sagas.

No one could understand the code, I fought it a few days before deciding to manually document its cases by trying all input combinations I could think of and just rewrote it fromscratch in less than 250 locs. Took me an afternoon to rewrite it and do the maintenance task.

If I had e2es since the beginning I could've figured it out sooner..

Yes, and given its not documented there are bugs in the underling business process which end up getting encoded into the software...

Yes! And I love it when the business says they want to innovate, or improve efficiency, but they aren't willing to document and analyze the business process. Sure, we can implement your process as you communicate it to us, but I wouldn't call that innovative. Innovative would be modifying to process to take advantage of some new technology or model.

Conway’s law, holding on line 2.

I disagree with this (sort of) for a couple of reasons:

1. For one, I think it's hard enough just to keep technical documentation up to date. Keeping separate business process docs up to date with code feels like it would be a collosal task.

2. That said, most software at least starts with some amount of requirements (whether that be a formal spec or a bunch of Jira epics). I have rarely seen any engineer start first by reading all of the old business requirements before trying to understand the code.

3. Even if the business requirements were documented perfectly, I rarely find that they are the major issue with understanding a code base.

Business data / process flow is so stable compared to a software implementation that having quality documentation pays dividends again and again. If you could document only one thing, document the business data flow.

Some industries are subject to control audits. So documenting the processes serves two purposes.

If the business doesn't know their process well enough to document or explain it, don't you think there will be water effort and rework, especially for edge cases?

It’s not a colossal task if you hire technical writers.

Isn't coding basically documenting the business processes? (just in a way/language that computers can understand and read). Why document it twice? That's just violating DRY/SRP no?

Reply on news.ycombinator.com