¿En qué tiempo gramatical debo escribir mis especificaciones?

21

Actualmente estamos escribiendo especificaciones funcionales y técnicas en un formato de dos columnas; oración resumida y detalles técnicos. Los detalles a menudo se refieren a un apéndice con diagramas, diseños de diseño, etc.

Sin embargo, estoy luchando con el tiempo para escribirlo:

Con el tiempo pasado como si el trabajo estuviera hecho, lucho por mostrar extensiones destacadas del trabajo existente. El tiempo futuro, ya que tiene que hacer X, comienza a sonar como una lista de tareas o un tiempo neutral muy fuerte, ya que se va a hacer o se hace.

Para agregar más confusión, esta especificación puede ser leída por personas que no tienen el inglés como primer idioma.

documentation specifications writing John
fuente

Respuestas:

12

Tenemos mucho de eso en mi último lugar de trabajo.

Los gerentes de producto han elegido usar el tiempo presente para describir lo que se debe hacer , como:

El usuario envía un pedido. El sistema envía un mensaje de confirmación.

Lamentablemente, la descripción de las condiciones previas también se realizó en tiempo presente, como:

El usuario coloca un artículo en el carrito de compras y especifica la cantidad.

Esto me ha causado mucha confusión, ya que no está claro lo que ya está y lo que está por venir. He tratado de hacer que usen algún tipo de tiempo futuro, pero nunca tuvieron que cambiar. Personalmente, no pude acostumbrarme en todos mis dos años allí. Simplemente no tiene ningún sentido, parece que alguien no tiene dominio de los tiempos verbales.

Por lo tanto:

  • Use un tiempo presente para lo que ya existe

  • Use un tiempo futuro para lo que debe hacerse. Emplea los mundos "debería", "debe", "hará".


fuente
El paso importante para recordar es volver a visitar las especificaciones. Asegúrese de actualizar la redacción de futuro a presente cuando se haga.
Ben L
@BenL: No, eso está mal. El tiempo se utiliza para proporcionar una implementación correcta, no para indicar el estado de la implementación. Aquí, el tiempo futuro se usa para indicar un estado de aplicación futuro, no un estado de implementación futuro. Por otro lado, vale la pena señalar que el enfoque recomendado aquí también es utilizado por la mayoría de los RFC. Vea RFC 2119 para la discusión de los términos must / required / would (would), should / recomendado (not) y may / opcional.
Brian
5

El tiempo presente me parece bien.

  1. Precondición: Foo está en estado X
  2. Operación: esto y aquello suceden
  3. Poscondición: Foo está en estado Y

todos están en tiempo presente.

O si es un "estado del proyecto"

  1. Versión 10: tiene características A, B, C y D

  2. Versión 10.1: contiene mejoras para A. Corrige el error 1049 en B. Agrega la nueva función E.

CashCow
fuente
2

Las especificaciones son instrucciones. escríbelos en tiempo presente. Me gusta esto.

Steven A. Lowe
fuente
1

Cuando creo diseños para software, prefiero el tiempo presente, incluso si creo los diseños antes de que exista el software. Incluso después de implementar una aplicación de software desde el diseño, el diseño sigue siendo un documento relevante e importante. Es muy posible que un documento de diseño siga siendo relevante durante un período de tiempo más largo después de que se implemente el software que antes de que se implemente.

Dan Stevens
fuente