Crear un sitio web y documentación efectivos de la biblioteca C ++

Crear una biblioteca C ++ también significa documentarla para que otros puedan usarla, y esa documentación puede variar drásticamente en calidad.

¿Cómo debe estructurarse un sitio web para una biblioteca C ++ para que sea más efectivo?

Enmarcaría "más eficaz" como dividido entre tres grupos específicos de interesados ​​de la biblioteca, que deberían poder encontrar y aprender lo que necesitan para participar y utilizar la biblioteca:

1. Los nuevos usuarios necesitan una introducción, descarga, configuración y documentación excelentes y fáciles que fluyan claramente de un paso al siguiente.

2. Los usuarios experimentados necesitan una referencia sólida con acceso rápido a los detalles que necesitan e información clara sobre nuevas actualizaciones.

3. Los nuevos contribuyentes necesitan una guía que cubra los pasos que deben seguir para llevar sus contribuciones a la biblioteca.

Me gustaría descubrir cómo hacer que cada uno esté muy contento con lo que ven y usan. Esta pregunta es un cruce entre la programación profesional y la experiencia del usuario.

Para ejemplos específicos, Boost es una de las mejores colecciones de bibliotecas, pero la instalación inicial, la documentación de referencia y descubrir cómo contribuir puede ser algo confuso.

Por otro lado, he encontrado que cppreference.com y la documentación de SGI STL son muy claros y útiles con explicaciones, enlaces y ejemplos.

Si bien los ejemplos son meramente opiniones y otros pueden diferir, ayuda a dar contexto a la pregunta que estoy haciendo.

En mi empresa anterior, comenzamos a generar documentación y a ejecutar un trabajo de CI todas las noches y publicarlo como un conjunto de páginas web a las que luego se referiría la wiki de nuestro equipo.

Como se sugirió en los comentarios a su pregunta, utilizamos doxygen. Una cosa que realmente me gustó y que se introdujo en la versión 1.8 fue la capacidad de tener un directorio (o árbol completo) de documentos de descuento, mientras que antes se generaba doxygen únicamente a partir de archivos fuente.

La estructura que teníamos era una pantalla de bienvenida (markdown) que tenía enlaces a varios lugares. Uno de ellos era una arquitectura de producto que mostraba una vista de 30,000 pies del producto y destacaba los principales servicios. Luego, desde esa página, hubo me gusta en otras páginas de descuento que ampliaron cada uno de los servicios y presentaron un diseño de muy alto nivel de cada uno (¿vista de 10k pies?).

También desde la página principal, teníamos enlaces a colecciones de guías de usuario que escribimos para explicar cómo usar algún código de utilidad / marco común.

Y lentamente comenzamos a migrar documentos de diseño existentes (escritos en MS Word y almacenados en punto compartido) en formato doxygen que en realidad resultó más fácil de lo que cabría esperar. Si no fuera por los diagramas, que debían exportarse individualmente y guardarse como JPEG, un documento de diseño de 20-30 páginas podría convertirse al formato de marcado de doxygen en aproximadamente 15-30 minutos y era tan simple que una cooperativa podría hacerlo ^{( *)} .

La belleza que me encantaba de usar doxygen para este tipo de documentación además de que podía generar HTML o PDF desde la misma fuente, era que podíamos vincular toda nuestra documentación directamente a las páginas de referencia de clase / función generadas al analizar archivos de encabezado. Por lo tanto, era una estructura muy agradable que iría desde "bienvenida" -> "arquitectura" -> "diseño" -> hasta la documentación a nivel de clase.

Y como todo estaba en Markdown, fue muy simple generar contenido (mucho más fácil que intentar explicar a un equipo de ingenieros cómo usar correctamente los estilos de MS Word) y la documentación se verificó allí mismo con el código fuente, para que Se introdujeron nuevas versiones y se modificó el diseño / arquitectura, la documentación siempre se sincronizaría con ella.

---

^(*) - j / k tuvimos grandes cooperativas (en su mayor parte) e hicieron muchas contribuciones increíbles al producto, pero hice que uno de ellos hiciera parte de la conversión de documentos.