Once there is an agreed concept of what changes would be required to solve a problem, a good engineering practice is to write a design document and solicit feedback from peers, users and stakeholders.
Often companies have internal templates on how to write good design documents. However, I have seen many engineers miss stating key information in their documents. This post hopefully can provide an overview of what information is useful for reviewers.
What is the problem?
In simple terms (and with as less industry or company jargon) call out missing functionality for users. Enumerate data and sources that support this claim.
If there is an accessible data set that reviewers can explore on their own, that is even better.
What is the cost of maintaining status quo?
Extrapolate usage growth, system maintenance, and usage issues to highlight why this problem needs to be solved now.
What is (are) the system(s) in which the problem manifests itself?
Compare and contrast the system(s) with the real world. Discuss the missing and or incorrect assumptions that led to the situation.
This typically leads into discussions of software architecture, platform models, and business context.
Most problems arise because the system model has diverged from the real world.
For example, the business direction may have shifted or the costs of labor have gone up or competitors have put pricing pressure on your offerings or the business wants to shift in a new direction (for instance the shift from perpetual licensing to software services).
Propose alternative solutions
For each proposed solution, discuss pros and cons. Ensure that both short and long term concerns & benefits are discussed rigorously.
Recommended an approach, and compare it to other alternatives
Recommend one of the proposals and provide details on work would be done by engineering teams.
In addition to required research, coding, and testing, also discuss needs for integration, deployment, security and compliance.
Provide an estimate of the project plan and costs
Discuss impact on existing processes, procedures and policies.
Estimate man power costs in terms of man months, and an ideal approximate high level project plan. Remember to list out milestones that provide incremental value to users.