Escribir un manual para desarrolladores de toda la empresa


17

Yo trabajo para una pequeña empresa. El brazo de desarrollo de software de la compañía antes de que me contrataran consistía en un tipo autodidacta con exceso de trabajo. Ahora que he estado escribiendo software para la empresa durante algunos años, se me ha encomendado la tarea de establecer prácticas formales de desarrollo de software para toda la empresa. Actualmente no tenemos pautas, aparte de

Escriba el código, pruébelo, póngalo en un archivo .zip y envíelo al cliente. Puntos de bonificación para TDD y control de versiones.

Mi jefe quiere que escriba un manual para desarrolladores de software que defina los procesos, protocolos, herramientas y pautas generales que utilizamos para hacer las cosas. En otras palabras, quiere un libro "Esto es lo que hacemos aquí" para que sea más fácil familiarizar a un nuevo empleado con la forma en que hacemos las cosas, así como para ayudar a mi jefe a comprender qué están haciendo sus secuaces y cómo lo hacen. eso.

A mi modo de ver, estoy sentando las bases y hay que hacerlo bien. ¿Cómo elegirías los temas para tal manual? ¿Puedes proporcionar algunos temas de ejemplo?

Nota al margen: si es importante, somos principalmente una tienda Microsoft .NET. Y estamos viendo prácticas ágiles como XP y Scrum, pero es posible que tengamos que modificarlas en gran medida para que funcionen en nuestra empresa.


3
Tu proceso actual es muy pobre. ¿Tiene el apoyo de la compañía para cambiar su proceso actual? No será barato, el tipo de cambio que se requiere tomará dinero. Hay muchos libros sobre el tema, la mayoría de esas prácticas tienen herramientas, que se requieren para implementar en ellas de una manera que no requiera un gran esfuerzo.
Ramhound

comprando temas del manual?
mosquito

1
@gnat Buen punto. Ver editar.
Phil

buena edición (aparentemente seguiste el enlace). También cambiaría los tipos de temas que crees que son importantes ... a algo como ¿Cómo medirías la importancia de los temas ... ? De esa manera, estaría más en línea con la guía de Jeff hasta donde yo entiendo
mosquito

1
Realmente no me preocupa cómo evaluar la importancia de los temas, ya que creo que ya puedo hacerlo. Más bien, estoy buscando ejemplos. Siempre he considerado que las respuestas a preguntas abstractas son mejores cuando se acompañan con ejemplos. Ver editar. Por cierto, agradezco su ayuda para mejorar mi pregunta.
Phil

Respuestas:


20

Lo dividiría en secciones como

  • Personal actual: nombres y títulos (idealmente con fotos)
  • Solicitudes, inicios de sesión, datos para conocer y solicitudes de permisos para enviar
  • Marcadores a sitios de la compañía y sitios externos clave relevantes para el negocio
  • Aplicaciones que la empresa utiliza para comunicaciones, correo electrónico, reserva de salas de conferencias, pantalla compartida
  • Procedimientos para actividades relacionadas con la empresa, como el pago de recibos, la reserva de viajes
  • Configuración de la máquina del desarrollador. Describa el proceso de configuración de una nueva máquina de desarrolladores en detalle. Por lo general, se 'espera' que solo tome un día, pero a menudo en realidad demora de 3 a 5 días.
  • El proceso de desarrollo, cómo se rastrea, asigna y actualiza el trabajo y qué herramientas se utilizan.
  • Cómo evaluar, qué evaluar, cuándo evaluar, dónde evaluar.
  • Estándares de codificación que incluyen convenciones de nomenclatura de archivos y estándares específicos de idioma.
  • Cómo manejar los errores, dónde documentarlos, cómo solucionarlos.
  • proceso de implementación, cuáles son las cosas clave que debe saber para impulsar la producción.
  • Cómo documentar, qué documentar, cuándo documentar.
  • Dónde están las cosas, por ejemplo, ubicaciones para el Código, Datos, Normas, Documentación, Enlaces y otros activos.

Hacerlo modular también le permitirá a usted u otros actualizar las piezas por separado, por ejemplo, los nombres y puestos de los empleados cambiarán con frecuencia a medida que las personas van y vienen.

Para cada sección, me esforzaría por escribirlo desde el punto de vista del 'novato'. Lo más importante será asegurarse de que realmente tenga sentido para un novato. Obviamente, su jefe no es la persona adecuada para revisar esto, ya que no es la audiencia prevista. Tiene razón en quererlo, solo asegúrese de que el contenido no termine siendo probado por él. Además, un 'novato' solo tiene "1 semana" como novato ... y solo tiene un punto de vista. Por lo tanto, es probable (y recomendado) que el documento se refine con cada nuevo empleado. De hecho, es una buena tarea asignarlos también para su primera semana, es decir, "Actualizar el manual para novatos".

Para Agile / SCRUM:

La parte más difícil de hacer Agile y SCRUM es 'realmente' hacerlo.

Para leer, comenzaría en http://agilemanifesto.org/ e iría desde allí.

También leería el conocido http://www.halfarsedagilemanifesto.org/ que agrega peso al hecho de que realmente tiene que abrazar todos los aspectos para que funcione. Si tiene que modificar en gran medida Agile para sus organizaciones, es probable que las personas quieran los beneficios, sin utilizar los procesos correctos. Este hecho en sí mismo debe presentarse para evitar cualquier medio asedio.


66
Me gusta la frecuencia con la que estás editando esto. Qué ... ágil de tu parte. :)
Phil

No estamos necesariamente queriendo modificar los principios ágiles en general. Simplemente modificaríamos prácticas específicas como XP, ya que realmente no tenemos la mano de obra para implementar todos los roles requeridos. Esa puede ser otra pregunta para otro día.
Phil

Lo sentimos, eliminé la respuesta por ahora porque la pregunta ha sido modificada.
Phil

1
Puntos de bonificación si configura un wiki de la empresa para contener esta información ...
Spencer Rathbun

Hola Spencer, eso es interesante. También comencé a usar un wiki de github con markdown. Alguna idea sobre cómo se comparan. Obviamente, muchas personas conocen github por código y markdown de SO, por lo que es fácil ser adoptado.
Michael Durrant

4

¡Parece que tendrá que introducir algunas prácticas antes de documentarlas!

a) Control de fuente: ¿cómo almacena sus fuentes y controla la revisión?

b) Gestión y seguimiento de versiones: ¿cómo hacer una compilación, numerar una versión, comparar un candidato de versión actual con una versión anterior?

c) Gestión de problemas: cómo rastrea los errores en sus versiones.

Estas son cosas bastante básicas, pero su implementación puede llevar mucho tiempo (y posiblemente costar dinero).


2
+1 por mantenerlo simple y concentrarse en temas importantes. Realmente no necesitamos mandatos del "gran gobierno" en los estilos de codificación.
kirk.burleson

3

Temas que incluiría en el manual de un desarrollador:

  • Roles / puestos dentro del departamento y sus correspondientes responsabilidades
  • Requisitos del software de la máquina del desarrollador (es decir, entorno de desarrollo requerido)
  • Dónde y cómo acceder al repositorio de código fuente
  • Herramientas de desarrollo que se utilizan (por ejemplo, IDE)
  • Estilo de codificación / estándares
  • Normas de documentación
  • Proceso de prueba
  • Proceso de construcción
  • Proceso de implementación
  • Proceso de soporte y gestión de problemas
  • Dónde obtener la versión más actualizada de este manual

Tenga en cuenta que este manual solo debe contener elementos específicos para el desarrollo y no información de toda la empresa (que debe estar en el manual de un empleado).


2

Uso de control de fuente

  • Qué herramienta de control de fuente está utilizando.
  • Sintaxis de comandos / herramientas comunes en el IDE.
  • Estrategia de ramificación / fusión.
  • ¿Cuál debería ser la unidad de un commit? ¿Cuánto tiempo es demasiado largo para tener un archivo desprotegido / no confirmado?
  • ¿Qué nivel de "cocción" denota un commit / check-in? Compila? ¿Pasaron las pruebas unitarias? ¿Revisados?
  • Lo que se espera que se incluya en las notas para un commit / check-in.
  • Procedimientos de reversión.
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.