You should never break interface.
You should expand interface.
If you do that.. then..
You never edit docs. You only add to docs.
If you do that.. then..
You never edit docs. You only add to docs.
Never refactoring your interfaces means that you can never improve the design as you gain new information. It means you can never change to something more appropriate if the underlying use cases change. It means that you can't easily consolidate common functionality in a different place as new similar interfaces are constructed. In other words, you are locking yourself in to a brittle system that will degrade into a mess of spaghetti that nobody can understand.
There are, of course, also downsides to refactoring. No simplistic rule of thumb will tell you your best approach.
If you can do it then great, but it's just not always technically feasible or cost effective.
A lot of times I find that developers lack experience of how legacy applications get the way they do. Either they have only ever worked on green field applications before (a surprisingly large contingent!) or they assume that the crappy legacy code was created because the previous developers were stupid. The reality is that most legacy systems were made with very reasonable decisions at the time, but that the world shifted under them. The mistake was locking themselves into their original decision and making it very expensive to change. The decision to never deprecate old APIs is one of those decisions that makes change expensive. Such decisions should always be made looking at the trade offs in cost. How expensive would it be if we changed this API? How expensive would it be if we don't change this API? Usually the second is far more expensive in the long run, but you have to take it on a case by case basis.
Yes, you should never change your interface.
But docs can poorly written (bad implementation) and deserve edits, just as code can be poorly written and deserve edits.