Post History

Source: https://writers.stackexchange.com/a/33064
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

I've done this sort of thing as part of evaluating technologies. It's usually cast as an _evaluation_, covering both benefits and weaknesses, rather than just weaknesses. I suggest getting clarification on whether to address benefits too.

The purpose of such a document is to help people make informed decisions about technologies or designs they don't fully understand. In my case, the decision-makers were product managers and business people, guided by engineers and other interested people. Your audience needs to understand the issues well enough to make decisions and doesn't care about the gory details. They care about _impacts_, not _implementation_.

You do something similar, though less formally, when you're considering major purchases. You probably don't know a lot about how your furnace works, but if you're not getting enough heat and a technician suggests that you could fix that by replacing your heat exchanger, you want to know enough about what that change would mean. (Maybe you're instead considering just buying some space heaters at a fraction of the capital cost.) In your case, your readers are people like you, making decisions about systems that they don't know all the details of. They need enough information to make an informed decision; they don't care about all the nitty-gritty details.

So, all that said, here's a typical structure for such documents in my experience. (I'm not aware of a specific template that's widely used.)

- General overview: a page or less on where you are now and what key factors need to be considered in an evaluation. Key factors might be things like security, standards compliance, compatibility, and maintainability. (If you were also evaluating alternate solutions, that would be covered here too. You don't seem to be asking about this kind of evaluation, sometimes called a _trade study_, so I'll omit it from the rest of this answer.)

- One section per factor. For each:

- Summary and recommendations: you've already made recommendations for each issue; this is where you pull them all together (at a higher level) for your readers. They need to _read_ the rest, but when they meet with the other stakeholders to make their decision, this last section is what they're going to be working from.

Here's a sketch of an example (omitting the final summary section):

> Evaluation of Flux Capacitor<sup>TM</sup> Architecture
> 
> Our Flux Capacitor v. 1.0 has been in production for a year. Feedback from customers and the industry has generally been positive, but key customers have raised some concerns and we have identified some issues in internal testing that would require architectural changes to address. These issues include: (list goes here)
> 
> 1. Activation Difficulties
> 
> The Flux Capacitor 1.0 is activated by engaging the control while traveling at exactly 88 MPH. (See next section for hardware dependencies and Delorean availability.) Many of our customers, particularly in the US, have raised concerns about legal and financial consequences.
> 
> The Flux Capacitor design depends on a configurable quantum harmonic frequency. The current value is 88; other possible values include 44, 22, and 176. Quantum harmonic frequencies are limited by the laws of physics and we can't choose a more convenient value like 65.
> 
> Pros:
> 
> - A speed of 88 MPH is achievable by all vehicular platforms under consideration. (Footnote: We previously abandoned consideration of low-power conveyances like Segways.)
> 
> - A speed of 88 MPH is high enough to make accidental engagement very unlikely. We have had only one report of such an accident, which occurred on the Autobahn.
> 
> - ...
> 
> Cons:
> 
> - 88 MPH is above the legal speed limit for most of our customers. We could mitigate this by speeding up the activation window so that law-enforcement officers are less likely to notice the speeding quickly enough to obtain a license number.
> 
> - We are having difficulty selling to elderly customers who prefer more moderate speeds.
> 
> - ...
> 
> Recommendations: Investigate using a quantum harmonic frequency of 44 MPH and adding safety features to prevent accidental engagement. This allows our users to comply with local laws and reaches the elderly market. The change would still allow the unit to fit in most of the platforms currently under consideration; it would not, however, fit in the Miata. We would need to design and user-test safety controls to prevent negative consequences from a trip down the interstate. This is a large-scale change requiring approximately $2M in engineering effort.

Original score: 5