una trabajo normas negocios los empresariales empresarial empresa ejemplos conducta comportamiento codigo apariencia documentation wiki business-logic

documentation - trabajo - ¿Qué es una buena solución para recopilar documentación de normas empresariales?



normas de conducta y apariencia (6)

Me estoy topando con una situación, en general, estoy seguro, donde la documentación de mi regla de negocios se distribuye a través de correos electrónicos, documentación (ahora desactualizada) y mensajes instantáneos. Esto apesta.

Puedo pensar en 2 alternativas: Sharepoint (odiarlo, la función de búsqueda es terrible) o un wiki.

Algunas cosas que me gustaría ver en la solución ideal:

  • Fácilmente actualizable : no me hagas sacar Word para actualizar los documentos
  • Vista diferenciada : a veces solo necesitas ver las novedades
  • Suscribible : Notificación de nuevos cambios en una página por página
  • Basado en roles : la edición y la visualización de páginas se pueden vincular a roles
  • Adjuntos : Fácil inclusión de maquetas, archivos, etc.
  • Búsqueda : es un mundo de Google post, quiero poder buscar y encontrar al instante: Sharepoint pierde en esta categoría, a menos que el que usamos esté configurado incorrectamente
  • Restricción de archivos adjuntos : idealmente, la solución no permitiría cargar un montón de documentos de Word que luego llamaríamos a nuestra documentación. Me gustaría que la documentación tuviera un formato consistente (y simple). Aplicación de archivos adjuntos como PDF, txt y así sucesivamente.

Siguiendo mi comentario de wiki, parece que hay al menos 3 wikis que hacen lo que quiero (Incentivo, SharePoint-Wiki-Plus, ThoughtFarmer). ThoughtFarmer, ama ese nombre.

+ 10⁶ para un Wiki, es la mejor solución que he encontrado hasta ahora para documentación, especialmente documentación técnica. En mi opinión, las ventajas de los "buenos" motores Wiki sobre los documentos de Office en un VCS son (pero ya lo sabe, ya que esta lista de características está muy cerca de sus requisitos):

  • simplemente son más rápidos y más fáciles de usar que los documentos de Office en un VCS (no es necesario abrir el cliente VCS, verifique la última versión, opcionalmente bloquearlo, abrir palabra, guardar, registrar, liberar el bloqueo)
  • están basados ​​en texto, por lo que usted hace diffs (a diferencia de word) y esto es algo que debe tener
  • ofrecen mecanismos de notificación (por ejemplo, correo, RSS) y, por lo tanto, la información se envía a usted (a diferencia de un VCS en el que tiene que extraer el documento cuando está desactualizado)
  • no hay un "documento bloqueado por otro problema del usuario" porque alguien se olvidó de liberarlo (si está utilizando el bloqueo exclusivo, lo que suele ocurrir con los documentos que no puede combinar)
  • Las páginas se pueden refaccionar, reorganizar y ensamblar fácilmente en documentos más grandes.
  • son realmente colaborativos
  • proporcionan un soporte mucho mejor para el código (por ejemplo, puedes apuntar directamente al código fuente en un VCS con un formato mucho mejor que en Word)
  • pueden indexar el contenido de las páginas y los documentos adjuntos (pdf, documentos de oficina, etc.) y hacer que se puedan buscar

El único problema al que me he enfrentado al utilizar un Wiki para la documentación es que es más difícil versionar la documentación al mismo tiempo que su código (es decir, usted entrega la versión xyz y quiere "bloquear" la documentación de esta versión). He utilizado las exportaciones para resolver esto, pero no es perfecto.

Ya he trabajado con TWiki Foswiki , Confluence y XWiki . Todos son motores "buenos" de Wiki (como se define arriba) y todos cumplen con sus requisitos. Por lo tanto, la elección final puede depender de sus restricciones (licencia, precios, tecnología) y preferencias personales.

A partir de hoy, elegiría Confluence si una herramienta comercial es una opción, XWiki si no lo es.

Estoy desarrollando uno.

Hace aproximadamente un año busqué el software de administración de requisitos en la red y encontré al menos 30 de ellos en aproximadamente 3 categorías:

  • No tiene precio (y se comercializa, por ejemplo, en compañías aeroespaciales)

  • Caro (por ejemplo, $ 1000 por asiento), que mis empleadores nunca han elegido usar

  • Barato o gratis, pero faltan características que me parecen importantes.

También hay herramientas de uso general (por ejemplo, Wiki, o correos electrónicos y documentos de Word y / o Hojas de cálculo), que también carecen de características que me parecen importantes.

Creo que deberías elaborar re: "faltan características que me parecen importantes".

Hay cosas que puedes hacer con un Wiki de propósito general:

  • Crear una lista de características
  • Describa cada característica (tal vez una página / sección separada para cada característica)
  • Haga esto de manera colaborativa (control de versiones, notificaciones de actualizaciones, páginas de discusión)

Pero, hay algunas cosas que creo que no puedes hacer con un Wiki de propósito general, incluso cosas bastante básicas:

  • Defina atributos personalizados (por ejemplo, "Fecha de inicio", "Costo estimado", etc.); asocie estos valores de atributo con sus características; enumerar las características (en una tabla o cuadrícula) con sus atributos (para que puedan ordenarse, por ejemplo, ordenadas por "Importancia" o por "Dificultad")

  • Ayuda con la trazabilidad (la trazabilidad no es demasiado difícil cuando solo hay dos etapas, por ejemplo, "requisitos" e "implementación", pero es más difícil cuando hay varias etapas, por ejemplo, "casos de uso", "especificaciones funcionales", "arquitectura", "implementación detalles "," casos de prueba "," resultados de prueba "e" informes de errores ")

  • Admite información estructurada, es decir, subsecciones y no solo secciones de nivel superior.

Incluso simplemente editar no es tan bueno como debería ser. La gente de negocios podría preferir usar una interfaz de usuario de MS Word para editar: pero MS Word produce documentos, es decir, "silos de información"; pero si no usas MS Word, ¿entonces qué estás usando? ¿Un editor WYSIWYG en el navegador? ¿O sintaxis de reducción?

Hemos utilizado JIRA en un proyecto anterior para almacenar alrededor de 750 reglas de negocios diferentes. JIRA es principalmente una herramienta de seguimiento de errores, pero es tan potente y personalizable que puede usarla para todo tipo de situaciones de flujo de trabajo / proceso / base de conocimiento. (Por cierto, no trabajo para la empresa que lo produce).

  • Fácilmente actualizable: si
  • Vista de diferencia: un historial de cambios completo está disponible
  • Suscribible: sí, tiene la idea de "ver listas"
  • Basado en roles: sí, modelo de seguridad rico en características
  • Archivos adjuntos: sí, cada regla puede tener sus propios archivos adjuntos
  • Búsqueda: sí, búsqueda de texto completo disponible
  • Restricción de archivos adjuntos: hmm: no estoy seguro de esto y exactamente lo que estás tratando de hacer.

Algunos consejos si decides ir por este camino ...

  • Utilice las ID personalizables de JIRA en otros lugares para referirse a la regla, por ejemplo, MYPRJ-334
  • Tenga pautas claras sobre qué significan los estados que planea usar, Propuestos, Aprobados, Implementados, Verificados, Eliminados.
  • La única definición de una regla está en la descripción: todos los comentarios son solo comentarios
  • Puede vincular la regla a los casos de uso, los componentes que sean

Es un gran enfoque y realmente lo recomendaría.

Me gusta usar la característica de Wiki incorporada en FogBugz para esto, asumiendo que ya la usas para el seguimiento de características / errores. Es útil tener esa información en la misma herramienta.

Una idea más FitNesse es mirar FitNesse . Es un wiki, dirigido principalmente a describir reglas de negocios (o requisitos de aceptación) como pruebas.