¿Cómo escribir documentación de recomendación?

He hecho este tipo de cosas como parte de la evaluación de tecnologías. Por lo general, se presenta como una evaluación y cubre tanto los beneficios como las debilidades, en lugar de solo las debilidades. Sugiero que se aclare si también se deben abordar los beneficios.

El propósito de dicho documento es ayudar a las personas a tomar decisiones informadas sobre tecnologías o diseños que no comprenden por completo. En mi caso, quienes tomaban las decisiones eran gerentes de producto y empresarios, guiados por ingenieros y otras personas interesadas. Su audiencia necesita comprender los problemas lo suficientemente bien como para tomar decisiones y no le importan los detalles sangrientos. Les importan los impactos , no la implementación .

Haces algo similar, aunque menos formal, cuando estás considerando compras importantes. Probablemente no sepa mucho acerca de cómo funciona su horno, pero si no está recibiendo suficiente calor y un técnico le sugiere que puede arreglarlo reemplazando su intercambiador de calor, querrá saber lo suficiente sobre lo que significaría ese cambio. (Tal vez, en cambio, esté considerando simplemente comprar algunos calentadores de espacio a una fracción del costo de capital). En su caso, sus lectores son personas como usted, que toman decisiones sobre sistemas de los que no conocen todos los detalles. Necesitan suficiente información para tomar una decisión informada; no les importan todos los detalles esenciales.

Entonces, dicho todo esto, aquí hay una estructura típica para tales documentos en mi experiencia. (No conozco una plantilla específica que se use ampliamente).

• Descripción general: una página o menos sobre dónde se encuentra ahora y qué factores clave deben tenerse en cuenta en una evaluación. Los factores clave pueden ser cosas como la seguridad, el cumplimiento de estándares, la compatibilidad y la capacidad de mantenimiento. (Si también estuviera evaluando soluciones alternativas, eso también se cubriría aquí. No parece estar preguntando sobre este tipo de evaluación, a veces llamado estudio comercial , por lo que lo omitiré del resto de esta respuesta).

• Una sección por factor. Para cada:

  • Describa el problema: ¿por qué nos importa?
  • Describa su arquitectura actual; ¿por qué existe este problema?
  • Pros y contras del enfoque actual (dos listas separadas). A menos que su problema sea muy complejo, debería poder cubrir cada entrada en una viñeta de tamaño razonable. Si puede hacerlo brevemente, puede incluir cómo mitigaría los inconvenientes.
  • Recomendaciones: solo para este problema, ¿qué recomienda cambiar? O si la arquitectura actual resuelve bien este problema, dígalo.

• Resumen y recomendaciones: ya ha hecho recomendaciones para cada problema; aquí es donde los reúne a todos (a un nivel superior) para sus lectores. Necesitan leer el resto, pero cuando se reúnan con las otras partes interesadas para tomar su decisión, esta última sección es en lo que trabajarán.

Aquí hay un boceto de un ejemplo (omitiendo la sección de resumen final):

Evaluación de la arquitectura Flux Capacitor ^TM

Nuestro Flux Capacitor v. 1.0 ha estado en producción durante un año. Los comentarios de los clientes y la industria en general han sido positivos, pero los clientes clave han planteado algunas preocupaciones y hemos identificado algunos problemas en las pruebas internas que requerirían cambios en la arquitectura para solucionarlos. Estos problemas incluyen: (la lista va aquí)

1. Dificultades de activación

El Flux Capacitor 1.0 se activa al activar el control mientras viaja exactamente a 88 MPH. (Consulte la siguiente sección para conocer las dependencias de hardware y la disponibilidad de Delorean). Muchos de nuestros clientes, particularmente en los EE. UU., han expresado su preocupación por las consecuencias legales y financieras.

El diseño del condensador de flujo depende de una frecuencia armónica cuántica configurable. El valor actual es 88; otros valores posibles incluyen 44, 22 y 176. Las frecuencias armónicas cuánticas están limitadas por las leyes de la física y no podemos elegir un valor más conveniente como 65.

Ventajas:

• Todas las plataformas vehiculares bajo consideración pueden alcanzar una velocidad de 88 MPH. (Nota al pie: Anteriormente abandonamos la consideración de medios de transporte de baja potencia como los Segways).

• Una velocidad de 88 MPH es lo suficientemente alta como para que sea muy improbable un enfrentamiento accidental. Solo hemos tenido un informe de un accidente de este tipo, que ocurrió en la Autobahn.

• ...

Contras:

• 88 MPH está por encima del límite de velocidad legal para la mayoría de nuestros clientes. Podríamos mitigar esto acelerando la ventana de activación para que sea menos probable que los agentes del orden noten el exceso de velocidad lo suficientemente rápido como para obtener un número de licencia.

• Estamos teniendo dificultades para vender a clientes mayores que prefieren velocidades más moderadas.

• ...

Recomendaciones: Investigue el uso de una frecuencia armónica cuántica de 44 MPH y agregue características de seguridad para evitar el acoplamiento accidental. Esto permite a nuestros usuarios cumplir con las leyes locales y llega al mercado de personas mayores. El cambio aún permitiría que la unidad encaje en la mayoría de las plataformas actualmente en consideración; sin embargo, no cabría en el Miata. Tendríamos que diseñar y probar controles de seguridad para evitar consecuencias negativas de un viaje por la interestatal. Este es un cambio a gran escala que requiere aproximadamente $2 millones en esfuerzo de ingeniería.

En caso de que esté comenzando desde cero y sea libre de elegir la forma que desee, debería echar un vistazo a la excelente respuesta de Monica Cellio .

Pero: en caso de que esté en una empresa establecida, es muy probable que no tenga que crear sus propias reglas de formato.

La mayoría de las empresas que han realizado este tipo de proceso varias veces tendrán algún tipo de guía de estilo o reglas sobre cómo escribir una recomendación. Hay muchas cosas que pueden tener que ser consideradas:

• ¿Qué tecnología se utiliza para presentar la recomendación?
  • PowerPoint como un breve resumen de gestión, tal vez además de un texto más largo
  • Palabra
  • Látex
  • ...
• ¿Qué estructura debe tener la recomendación?
  • Si bien existen reglas generales sobre cómo se puede hacer esto (nuevamente, mire la respuesta de Mónica), una empresa puede optar por tomar un camino diferente, y si su gerente ha leído una docena de recomendaciones antes, siempre con el mismo diseño general, entonces usted querrá que sea más fácil para él encontrar lo que está buscando.
  • También puede haber requisitos reglamentarios, según el sector en el que se encuentre su empresa; si está altamente regulado, es probable que la documentación se pueda utilizar como documentación para adherirse al proceso además de documentar su recomendación. Por ejemplo, su empresa puede verse obligada a evaluar al menos tres alternativas diferentes; en tales casos, puede haber guías de estilo que sean necesarias, por ejemplo, para decisiones de fabricación o compra.
• ¿Cuánto tiempo puede y debe ser?
  • Una guía de estilo de toda la empresa le dará recomendaciones sobre la longitud preferida de ciertas partes. Tal vez su exposición no pueda tener más de una página. O tal vez necesite tener al menos una página que hable sobre pros y contras.
  • Al observar los ejemplos anteriores, puede tener una idea de lo que funciona y lo que no funciona. ¿Una documentación larga equivale a una buena oportunidad de obtener financiación, por ejemplo?

Lo más importante al escribir una recomendación es preguntar a sus compañeros de trabajo si conocen tales guías de estilo y ejemplos, porque su texto puede ser perfecto, si no se adhiere a las pautas de la empresa, no será bien recibido.

Los anteriores son algunos puntos que debes tener en cuenta y sobre los que puedes preguntar. Tal vez no pueda encontrar un documento completo, pero encontró presentaciones de gestión con diapositivas de resumen. Eche un vistazo a cómo están diseñados y decida si sería una buena idea tomarlos como ejemplo. Por ejemplo, ¿está haciendo comparaciones simplemente enumerándolos uno debajo del otro? ¿O estás poniendo el Pro en el lado izquierdo y el Con en el lado derecho? ¿O compara dos productos como "El producto 1 es barato - El producto 2 es caro" con la siguiente línea "El producto 1 ofrece tres de las cuatro funciones solicitadas - El producto 2 ofrece cuatro de las cuatro funciones solicitadas"?

Al realizar un análisis de debilidades, ¿su empresa prefiere una pequeña diapositiva/página de descripción general, seguida de una página por debilidad y luego va a las "recomendaciones" para hablar sobre las estrategias para mitigar todas las debilidades juntas? ¿O su empresa prefiere abordar el problema en ese momento y quiere que le dé la debilidad directamente seguida de "recomendaciones" específicas sobre cómo mitigar el riesgo?

Finalmente un montón de "¿Cómo lo haría?" depende de cuanto tiempo tengas. Si se trata de una documentación que debe documentar lo que ha hecho en los últimos meses, la gente seguramente esperará que haga un documento largo con algunos párrafos cortos al principio y al final que le digan a la gerencia qué hacer y con descripciones largas en el medio. eso le dirá a sus compañeros de trabajo por qué recomendó lo que recomendó. Si no tiene mucho tiempo porque, por ejemplo, no es una tarea de alto perfil, tal vez solo un proyecto pequeño con un presupuesto aún más pequeño, entonces es posible que desee mantener todo corto. Los detalles dependen del contexto exacto, lo que puede encontrar como plantilla en su empresa u obtener como aporte de sus compañeros de trabajo más experimentados y su público objetivo.