¿Cuál es la mejor manera de almacenar documentación asociada con un proyecto de código?

10

Tenemos muchos documentos asociados con nuestro desarrollo de software. Estos incluyen cosas como requisitos, documentos de diseño, archivos PDF externos, archivos de clientes, instrucciones de prueba, etc. Actualmente, estos documentos están dispersos por todas partes (wiki, "algún lugar en la red", un disco duro de desarrolladores locales (!), e incluso lugares peores).

¿Cuál es la mejor manera de hacerles un seguimiento? Dado que utilizamos Visual Studio (2010) para nuestro desarrollo, y realmente no tenemos ningún desarrollador que no sea desarrollador en el proyecto, pensé que sería una gran idea almacenarlos dentro de la "solución" VS, lo que les permitiría ser controlado por la fuente y accesible universalmente por todos los desarrolladores.

Sin embargo, VS realmente no parece estar diseñado para hacer esto. Si edita cualquier archivo de documento, incluso uno que esté configurado con las propiedades de compilación "Ninguno", "No copiar", VS deberá reconstruir el software antes de que vuelva a ejecutarse. No hay forma de crear un "Proyecto de documentación" dentro de la solución. (Usamos un proyecto C # vacío para esto). Visual Studio y Word / Excel flat no hacen bien el control de código fuente. No puede ver un archivo registrado y luego decide hacer un cambio sin cerrar primero el archivo, ir al proyecto y retirarlo manualmente antes de realizar el cambio. Es lento y tedioso en el mejor de los casos.

De todos modos, este es el mejor que nuestro equipo ha ideado, pero realmente desearía tener una solución mejor (gratis).

David
fuente
¿Qué tan grande es tu equipo?
Jeff
Tenemos 3-4 en este momento.
David
¿Qué control de versiones estás usando específicamente? No conozco un control de origen en el que esté vinculado al uso de Visual Studio para administrarlo.
Earlz
Donde trabajo, utilizamos TFS para almacenar código y SharePoint para documentación, planes de prueba, etc.
Trabajo
44
No recomendaría poner documentos como PDF en VSS. Eso sí, tampoco recomendaría poner el código fuente en VSS.
Carson63000

Respuestas:

3

No estoy seguro de si hay una "mejor manera", pero según su descripción, parece que cada desarrollador está haciendo su propia forma de almacenar la documentación. Obtenga una aceptación de todos con un único método para almacenar documentación, y será mucho más fácil mantenerla organizada.

Además de la respuesta "encuentre la mejor manera para usted", diría que al menos busque una solución que facilite la búsqueda de documentos . En una compañía, configuré un wiki que contenía enlaces a archivos lanzados sobre serverland, lo que de repente hizo que fuera mucho más fácil buscar y localizar documentos sin importar dónde se encontraran. Una vez que otros usuarios comenzaron a usar el wiki para buscar documentos, también comenzaron a actualizarlo para vincular nuevos documentos o simplemente creando una entrada de wiki como documento.

Me encantaría saber de alguien más si conocen los sistemas de control de versiones gratuitos que funcionan bien con documentos. Lo único que sale de mi cabeza es Sharepoint, que no es exactamente gratis. He visto sistemas de versiones no oficiales donde las personas tienen una carpeta "Archivo", y simplemente colocan revisiones pasadas de un archivo en esa carpeta, con la última revisión en el mismo nivel de carpeta que "Archivo".

Jeff
fuente
Nuestra solución 'wiki' es un enlace al recurso compartido de red (o un enlace directo a archivos en la red. La desventaja es que no hay control de versión de eso. O bien puede descargar / editar / cargar el archivo en la wiki, que es un Proceso de 10 pasos cada vez que desee editarlo para corregir un error tipográfico.
David
muchas alternativas gratuitas de sharepoint (¡que son mejores!): pruebe Nuxeo para una sencilla de configurar. O Alfresco por algo con más poder, si lo necesitas.
gbjbaanb
La Búsqueda de Google instalada en su máquina hace maravillas para localizar cosas.
3

La solución que mejor funcionó en mi empresa fue configurar un wiki (utilizamos mediawiki). Se utiliza de muchas maneras, desde las entradas tradicionales de wiki a un simple "Esto es un ..." más un documento de Word. Es muy fácil de buscar. Estamos construyendo gradualmente un depósito de información muy útil.

Michael K
fuente
Hemos tratado de usar doku-wiki, pero es muy tedioso de usar (tratar de arreglar una palabra, el tipo de documento es 10 pasos tediosos), además de no tener soporte para múltiples usuarios sobre quién está editando qué. También hubo muchas advertencias y limitaciones sobre el tamaño y la extensión del archivo que realmente molestaron más que ayudaron. No obtuve el compromiso de usarlo de otras personas en la compañía. Veo un gran potencial, pero desafortunadamente no para mi compañía.
David
1

Al menos en VS 2008, puede establecer el tipo de configuración de un proyecto C ++ (en propiedades del proyecto-> general-> valores predeterminados del proyecto) en Utilidad , en cuyo caso VS no hace nada con él.

¿Has intentado utilizar un proyecto de este tipo en tu solución basada en C #? (¿Quizás un proyecto C # tiene algo similar?)

Macke
fuente
0

Definitivamente estoy de acuerdo en que no hay una solución única mejor aquí. Pero control de versiones! = Incluido en la solución; La mayoría de los sistemas pueden manejar cosas más allá del IDE. Por lo tanto, uno puede mantener los documentos cerca, pero en la mayoría de los casos.

Ahora, superar los molestos hábitos de Word para cambiar archivos cada vez que se abren es un problema diferente. . .

Wyatt Barnett
fuente
0

No, los proyectos de Visual Studio (bueno, C # y Vb.net) tienen un enfoque cerebral para el explorador de soluciones. El VC ++ es MUCHO mejor, ya que puede crear carpetas virtuales que no están vinculadas al diseño del disco y poner todo tipo de cosas allí también. Microsoft tonto lo rompió tratando de hacerlo "más fácil de entender".

Todavía puede ponerlo en una 'carpeta de soluciones' pero todavía no es tan flexible como probablemente desee. Eso significa que tiene que encontrar una alternativa y mis alternativas recomendadas son herramientas web. Si no desea probar un portal de proyecto (como Redmine) donde puede almacenar documentos y tener un wiki, un rastreador de errores, etc., entonces busque una herramienta de gestión de documentos. Algo como Nuxeo o Owl te haría bien. Una vez que es la web, tiene una ubicación central para que las personas sepan dónde buscar estas cosas; esa es probablemente la parte más importante de la administración de documentos. Si lo vincula a un sistema de control de versiones como subversion (¡continúe, no se arrepentirá después de VSS!), Aún podrá vincular los documentos a las herramientas web y controlarlos también.

Subversion incluso tiene la capacidad de exponer el repositorio como una carpeta webdav, es decir, una carpeta de red, por lo que puede colocarlos en una 'unidad de red' y aún así tener su versión controlada automáticamente.

Todavía iría por Redmine como mi preferencia personal.

gbjbaanb
fuente