Gestión de escritura de especificaciones

9

Simplemente no puedo imaginar escribir software sin una especificación. No importa cuán incompleto o alto sea, las especificaciones son importantes para explicar a los programadores despistados cuáles son las funcionalidades del programa.

Pero el problema con las especificaciones es que es un ciudadano de segunda clase en todo el ciclo de desarrollo de software; cuando el desarrollo toma el vapor, se descuida. Pero cuando surge una disputa, los desarrolladores y probadores y las ventas se apresuran a encontrar la especificación para justificar sus motivos.

O sucederán uno o más escenarios:

  1. La especificación no se puede recuperar, nadie sabe dónde está la especificación
  2. Diferentes versiones de la especificación surgen de diferentes fuentes; se necesita grandes dificultades para saber qué versión es la versión más reciente, o si es una versión más reciente disponible.
  3. La especificación está incompleta, faltan algunas partes de los documentos a los que hace referencia.

Por lo tanto, la gestión de especificaciones es importante, y es igualmente importante que todos tengan una sola fuente de especificaciones.

¿Cómo gestionas tus especificaciones? Intenté que todos usaran Google Docs, pero todos se opusieron. Todo el mundo está demasiado apegado y enamorado de Microsoft Word, que es, en su opinión, muy fácil de usar, muy fácil de insertar imagen, ecuación muy fácil de escribir y otras cosas.

¿Cómo convencerlos de que MS Word es simplemente terrible para compartir?

specifications Graviton
fuente

Respuestas:

6

¿Cómo convencerlos de que MS Word es simplemente terrible para compartir?

No pierdas tu tiempo.

Primero. Las especificaciones deben estar en texto plano (realmente) y bajo control de código fuente. Use Markdown o RST o alguna otra herramienta de marcado ligera para producir una página PDF o HTML. Texto sin formato.

Segundo. Toma las diversas fuentes. Fusionarlos. Escribe tu propio documento final.

Cuando se oponen, tienen dos opciones.

  1. Use Google Docs (o la herramienta de control de código fuente) para editar su versión.

  2. Continúe enviándole cambios que edite, filtre y transforme en el documento final.

Prefiero # 2. Alguien necesita "poseer" la especificación. Y un montón de gente (estilo wiki) conduce a debates y guerras de cambio y documentos paralelos y conversaciones fuera de línea y similares.

S.Lott
fuente
1
+1, y recuerda la Regla del Menos Poder - Cualquiera que quiera una versión elegante en un editor WYSIWYG puede simplemente copiar el marcado renderizado.
l0b0
@ l0b0: Buen enlace.
S.Lott
6

No creo que sea un problema de "herramienta" sino más bien un problema de "proceso" (o falta de proceso).

Probablemente ya tenga un proceso para lanzar software (prueba unitaria, prueba de integración, carta de lanzamiento, entrega, etc.), también necesita implementar un proceso de documentación.

  • ¿Quién va a escribir las especificaciones? ¿Quién los va a actualizar o mantener?
  • ¿Quién va a revisar las especificaciones?
  • ¿Quién va a aprobar las especificaciones? Arquitecto, Líder de proyecto, QA?
  • ¿Cómo se almacenan las especificaciones?
  • ¿Quién se asegurará de que no se usen versiones obsoletas?
Xavier T.
fuente
2
+1: los problemas de herramientas son a menudo síntomas de problemas de proceso.
S.Lott
sí tenemos un proceso, pero a las personas les encanta quejarse de que el proceso no funciona y cortar atajos siempre que sea posible.
Graviton
@Graviton: su problema principal es probablemente que la gerencia no puede ver el uso de la documentación y, por lo tanto, no impone reglas estrictas. Si quiere que las cosas mejoren, probablemente tendrá que mostrarles lo importante que es.
Xavier T.
4

Se requiere definitivamente algún tipo de control.

Debe ser versionado y firmado, y este proceso debe ser estricto.

En demasiados lugares, el cierre de sesión se descuida, y esto lleva a peleas de bollos.

La ubicación no importa mientras se pueda rastrear

  • Sharepoint
  • un disco compartido seguro y respaldado
  • ¡He visto algunos lugares usar su código fuente de control!

Pero, lo que es más importante, es necesario que todos los involucrados y 1 o 2 personas sean responsables de administrar tanto el documento como la firma, por ejemplo. El Gerente de Proyecto.

ozz
fuente
+1, sugiero que mueva el documento de especificaciones al control de origen si nada más ayuda. Una ventaja es que obtienes el historial de versiones. Incluso si no puede hacer diferencias de versión (a menos que encuentre un complemento que pueda hacer diferencias en los archivos de Word), puede extraer toda la versión y ver qué ha cambiado. Esto puede ser MUY útil en una disputa sobre especificaciones. La aprobación también es muy buena. Y también la importancia de que todos participen en el proceso (para que nadie pueda decir "¿cuándo se decidió eso?") No se puede enfatizar lo suficiente.
FrustratedWithFormsDesigner
0

MS Word está perfectamente bien para crear una especificación. Administramos el nuestro en SharePoint, que también maneja el control de versiones. Si no tiene a mano SharePoint u otro producto de administración de documentos, Google Docs está bien (ahora puede cargar archivos .doc / .docx sin convertirlos al formato de Google Docs). O, como otros han sugerido, incluso puede almacenarlos en su sistema de control de versión de código fuente (si las personas que crean las especificaciones tienen acceso a ese sistema).

Marcie
fuente
0 
 > How to convince them that MS Word is just terrible for sharing?

no puede comparar fácilmente cuál es la diferencia de dos instancias en un sistema de control de versiones.

No me gustan las especificaciones de palabras por ese motivo. Pero dado que es una decisión política usar especificaciones de palabras, tenemos como "información de historia" en la primera página con estas columnas:

número de versión (se refiere a la versión del producto), autor, fecha, descripción

k3b
fuente