documentation - studio - estandar de documentacion de codigo c#

¿Cómo organizas tu Documentación? (3)

Creo que vale la pena echarle un vistazo a la Programación Literaria , pero los equipos con los que he trabajado han tenido tanto éxitos como fracasos. Aquí es donde creo que la programación alfabetizada sería útil para usted:

Su documentación API y las pruebas unitarias deben escribirse juntas como un programa alfabetizado.
Su aplicación y la documentación interna para desarrolladores deben escribirse juntas como un programa alfabetizado.

La programación de Literate no lo ayudará con su guía de administrador o su guía de usuario.

En cuanto a cómo se organiza, es una verdad clásica que la estructura de su documentación refleja la estructura de su organización . O como dijo un viejo profesor mío, a medida que envejeces aprendes a preguntar quién sabe algo, no en qué libro está . No luches contra este fenómeno; ir con eso:

Su guía de usuario debe ser responsabilidad del líder de su equipo de usabilidad. O si su tienda es tan maloliente como todo eso, es el desarrollador de su equipo el más responsable de la usabilidad.
Su guía de administrador debe ser responsabilidad de la persona que va a recibir la llamada cuando algo no funciona en el sitio y debe ser resuelto ahora .

Estos detalles no son tan importantes como el principio general: organice su documentación en torno a las personas que tienen el conocimiento y la responsabilidad .

Necesito un sistema de documentación para un equipo. Este equipo, hombre, tenemos un gran servicio web y tenemos nuevos productos en preparación. Y actualmente, solo hay un wiki alojado en un sistema de trac. Y créeme cuando digo que la organización huele, bueno, muy al sur de queso. La mayoría de las veces que quiere encontrar algo como desarrollador, probablemente no lo encontrará.

Evaluaré las herramientas que nos ayudan a crear documentación. Pero primero necesito considerar cómo se organizará todo. Estoy pensando en dividir las cosas en una lista de diferentes tipos de documentos.

Documentación Stuff-that-exists

Cada uno de estos es un solo documento "entidad". Esto significa, probablemente una wiki.

API / Documentación de código - ¿Cómo codificas contra esto?
Guía de administración : ¿cómo mantenemos esto? (Somos un servicio web, así que esto es algo importante).
Guía del usuario : ¿cómo usan las personas estas cosas?

Documentación de fantasía de tierras

Básicamente, su documentación de planificación. Encuentro que necesitas agrupar funciones relacionadas. Luego, en algún punto, rompes estas características. Ergo, por cada bolsa de características, obtienes un único documento que responde dos preguntas:

Plan "Marketing Guy" : ¿cómo nos pagan? ¿Cuál es el valor de negocio aquí?
Plan Code Monkey - ¿Cómo funcionará?

Estoy interesado en ver cualquier variación sobre cómo se organiza. O bien, ¿encuentra formas alternativas de comunicarse, que reemplaza cualquiera de estos documentos básicamente estáticos?

En lo que respecta al contenido:

Nuestra metodología SDLC dicta qué documentos necesitamos escribir.
Nuestro proceso de control de documentos dicta cómo nombramos y versionamos los archivos.
Nuestro proceso CM dicta cómo persistimos estos archivos.

Solíamos almacenar todo en nuestra LAN, a través de varias unidades y directorios, según el producto para el que estaba la documentación y el área funcional que lo producía. Fue un desastre. Por lo tanto, cambiamos todo a SharePoint pensando que facilitaría la búsqueda de documentos. No fue así. Entonces, intentamos algo diferente:

Toda la documentación para un producto se organizó en un único repositorio para ese producto. IOW, cada producto tiene su propio repositorio de documentos. Aún conservamos todo en SharePoint, pero creamos un sitio de SharePoint para cada producto y usamos una biblioteca de documentos personalizada, con metadatos personalizados, para los documentos.
Dejamos de nombrar documentos usando acrónimos y abreviaturas. El plan de prueba del sistema simplemente se llamaba System_Test_Plan.doc. La especificación de los requisitos de la empresa se denominó Business_Requirements_Specification.doc.
En lugar de crear carpetas en SharePoint, creamos vistas para filtrar y agrupar documentos. Además, encontramos que los metadatos facilitan que SharePoint encuentre documentos al realizar búsquedas.
Para las guías de administración y los documentos de tipo de soporte del sistema, utilizamos una wiki de SharePoint en lugar de documentos, lo que también parece facilitar que SharePoint encuentre las cosas.

La clave, como usted alude a lo anterior, es facilitar la búsqueda de documentos / información.

La administración y las guías de usuario generalmente se escriben mejor como páginas de Wiki, asegurándose de que se rompan en fragmentos claros y sensibles en lugar del estilo de "big-old-word-file". Estas secciones cambiarán con frecuencia y probablemente se escribirán en colaboración, con muchos consejos escritos a medida que pasa el tiempo, que nada supera la flexibilidad. El uso de una Wiki también le brinda el beneficio de las versiones integradas.

La documentación API es difícil. El problema principal es el siguiente: cuando alguien escribe la documentación de la API, hay una tendencia a suponer que quien invoque esos servicios leerá la misma documentación con escrutinio. ¡Esto no sucede! . La gente hará todo lo que esté a su alcance para evitar la distracción de tener que ir y leer la documentación de una llamada, o la echarán un vistazo, o buscarán cosas muy específicas. Esto dará lugar a problemas. Esto es malo incluso cuando la gente necesita "pasar el mouse" por una llamada en un IDE. Una API basada en web con documentación basada en web será aún peor.

Desafortunadamente, no hay mucho que puedas hacer para contrarrestarlo. He tenido algunos buenos resultados iniciales con una herramienta que alerta a las personas que llaman a información importante en un método invocado, pero eso es específico de Java.

Lo que puede hacer para mejorar ligeramente la situación en el caso de la documentación de la API , es leer detenidamente la documentación de cada servicio / función, una vez muy rápido y una muy a fondo, y observar las diferencias. Algunas, pero no todas las documentaciones incluirán "directivas": cosas que el cliente realmente necesita saber , como advertencias, problemas de rendimiento, efectos secundarios, requisitos imprevistos, etc., que serán una sorpresa. Asegúrese de hacer que estos sean visualmente distintos y muy destacados para que quien visite la documentación de la API se dé cuenta de ello.

Contáctame directamente si quieres más información sobre esto. Estaré encantado de compartir ejemplos y consejos.