Usando MAML para la documentación conceptual de la biblioteca [cerrada]

Question

Estoy trabajando en una nueva biblioteca y estoy usando los comentarios XML para la documentación de la API junto con castillos de arena que funciona muy bien.

Pero tengo que escribir la documentación adicional que cubre los conceptos, la arquitectura global, trabajando demos, etc, etc diagramas de clase.

Tengo 2 opciones:

1. Uso algunos motores de wiki y documentación escritura estilo wiki.
2. Uso MAML que parece ser para este propósito.

El uso de wiki parece solución segura porque hay muchos estable, motores populares y gratuitas disponibles, pero la API y la documentación conceptual no va a ir de la mano (de entrecruzamiento, apariencia, etc.). Usando MAML significa una curva de aprendizaje y no estoy seguro acerca de su grado de madurez que es y cuáles son sus ventajas / desventajas.

¿Ha utilizado MAML / Wiki para este propósito y cuáles han sido sus aprendizajes? ¿Qué me sugiere?

Answer 1

En lo personal, me encanta la libertad de trabajar w / un Wiki. En este punto, usted tiene algunas opciones decentes para la edición de MAML

• DocProject
• Sandcastle Archivo de ayuda Constructor

No puedo hablar mucho para DocProject (aunque se ve bien). En este momento, estoy usando SHFB a documentación de la API de combinación y algunos documentos conceptuales en MAML. El editor es decente y más que suficiente para mis necesidades. Soy capaz de configurar fácilmente una tabla de contenido y enlace entre mi API y documentos conceptuales. Un buen recurso para mirar a los ejemplos es SandcastleStyles .

Al igual que con todas las cosas, hay algunas preguntas importantes.

• ¿Tiene alguna requisitos para enviar su documentación en un solo paquete? En mi caso, tenía que enviar todo en un buen paquete compilado. No se puede hacer eso w / un Wiki, pero se puede hacer que w / castillo de arena.
• ¿Usted va a ser la única persona de actualizar el contenido conceptual? La mayoría de los wikis tienen un muy buen editor y una capacidad de enlace rápidamente entre los temas. La única herramienta que necesita para editar el contenido es un navegador, lo que podría ser un requisito para un escritor menos con conocimientos técnicos.