Documentar un lenguaje de programación: Manual de referencia

Estamos buscando renovar la documentación en nuestra línea de productos. Parte de eso incluye manuales de referencia para un lenguaje de programación utilizado como parte del sistema.

Al escribir un manual de referencia para un lenguaje de programación, ¿cuál es la mejor manera de estructurarlo para una máxima usabilidad para los nuevos en el lenguaje?

¿Cuáles son los aspectos clave para cada palabra clave documentada?

• Sintaxis
• Descripción
• Argumentos - si corresponde
• Valores de retorno - si corresponde
• Ejemplo de uso?
• ¿Me faltan otros?

¿Deberían documentarse también conceptos (como estrategias de bloqueo, detalles relacionados con el rendimiento) en este manual de referencia, o es un documento separado?

_{Esto es para consumo externo. Ya tenemos conjuntos de documentos completos (consulte: http://www.rocketsoftware.com/u2/resources/technical-resources ). Resolviendo lo que deberíamos hacer diferente: ya tengo mis ideas, pero como siempre, trato de no confiar únicamente en mi opinión.}

_{Audiencia: Desarrolladores técnicos que utilizan nuestras bases de datos y herramientas para producir software en muchas industrias.}

Organice la documentación de acuerdo con las necesidades del público objetivo.

En su caso, la audiencia principal son aparentemente desarrolladores de software. Las partes a considerar aquí son abordar diferentes "sub-audiencias" de este:

1. Hola Mundo.
   Aquellos que estén dispuestos a probarlo rápidamente, simplemente compilen y ejecuten una aplicación de muestra para ver cómo se ve.
   Piense en la audiencia como una dirigida por MySQL "regla de 15 minutos" :
   

   _{... un usuario para poder tener MySQL en funcionamiento 15 minutos después de que haya terminado de descargarlo.}

2. Fundamentos
   Para los chicos dispuestos a aprender rápidamente las cosas necesarias para comenzar a producir software de trabajo.
3. Temas avanzados.
   Para desarrolladores que ya conocen y practican los fundamentos, interesados ​​en saber qué hay más allá. Temas principales que no se han cubierto en Fundamentos .
4. Guía de estilo / prácticas recomendadas.
   Asesoramiento subjetivo y orientación para aquellos interesados ​​en la forma en que recomienda hacer las cosas.
   _{La pregunta no indica si esto podría tener una audiencia sustancial en su caso, por lo que las opciones a considerar son incluirlo como parte / apéndice de temas avanzados o incluso descartarlo por completo.}
5. Quirks
   Temas oscuros, fuera de la corriente principal, que podrían ser de interés para una fracción bastante limitada de su audiencia. Por ejemplo, si tiene una línea heredada, o cosas como actualización / migración / interoperabilidad con legado, póngala aquí. Si hay algunos efectos secundarios para alguna función en un entorno "exótico" particular, se incluye en esta parte.

^{¿Qué pasa si algo en el manual es cuestionable / ambiguo? ¿Qué pasa si resulta que una explicación exhaustiva de conceptos particulares haría que ese manual fuera demasiado difícil de leer? ¿Qué pasa si resulta que esa versión particular del manual tiene errores?}

Dos cosas a considerar para los mantenedores son:

1. Especificación técnica / formal.
   Siempre que haya un tema cuestionable / ambiguo / difícil de explicar en el manual, se puede referir al lector a un párrafo particular en la especificación para una declaración estricta y clara, "oficial" sobre eso. La descripción estricta y completa (y probablemente aburrida) de la sintaxis del lenguaje iría mejor allí.
   Las consideraciones más importantes para la especificación son la precisión técnica y la integridad, incluso si esto se produce a expensas de la legibilidad.
2. Suplemento en línea.
   Simplemente reserve una URL y colóquela al comienzo de cada documento que publique, para que los chicos que se pregunten qué demonios acaban de leer puedan ir allí (en lugar de molestar a los mantenedores manuales) y encuentren el error explicado.

   _{Errata> Fundamentos> Versión 2.2> Error tipográfico en la página 28, la segunda oración comienza con suerte , lee bloqueo en su lugar.}

Por ejemplo, los mantenedores manuales aparentemente estarían interesados ​​en una descripción completa y precisa de la concurrencia y el bloqueo en la especificación formal: póngala allí. Los lectores de temas básicos o avanzados pueden estar interesados ​​en una descripción general / introducción / guía extraída de la especificación y adaptada a sus necesidades, etc.

_{Podría ser útil organizar un estudio comparativo de la documentación de referencia proporcionada para otros idiomas como el suyo. Apunte este estudio a aprovechar la experiencia adquirida por aquellos que lo hicieron antes y aprender a evitar los errores que cometieron.}

_{Lo último, pero no menos importante, considere configurar el desarrollo de documentación de una manera similar al desarrollo de software. Me refiero a cosas como el control de versiones, lanzamientos regulares, seguimiento de problemas, control de calidad, etc. Sin embargo, es posible que desee hacer algunos compromisos si resulta que su (s) escritor (es) técnico (s) no se sienten realmente cómodos con cosas como esa. No queremos obtener contenido malo "a cambio" para un proceso de desarrollo perfecto, ¿verdad?}

Lo primero que debe hacer es evaluar a la audiencia. ¿Es su audiencia hackers del kernel de Linux o son diseñadores de hardware que usan herramientas de software para hacer un trabajo pero no están interesados ​​en el software per se y no tienen experiencia en CS? Es probable que los ingenieros eléctricos no sean completamente claros sobre las diferencias entre argumentos constantes y no constantes, punteros a objetos versus referencias, etc. Si sus primitivas tienen nombres sobrecargados, entonces es mejor que explique ese concepto en un nivel apropiado para su audiencia, que podría no ser nada si son programadores de C ++.

Lo segundo que debe evaluar es la granularidad de las primitivas del lenguaje. Cuanto más fina sea la granularidad, más necesitará proporcionar ejemplos de uso en proximidad a las especificaciones de sintaxis de cada primitiva. Es decir, si tiene una primitiva de bajo nivel que crea una instancia de algún contexto, y necesita operar con otras tres primitivas de bajo nivel antes de poder hacer algo útil, entonces será mejor que tenga un ejemplo completo de alguna función útil cercana. por en el manual. Consulte la documentación en línea de OpenSSL para un excelente contraejemplo de documentación casi inutilizable.

Asegúrese de incluir una explicación de los efectos secundarios de sus funciones.

En cualquier caso, si no desea que los programadores de su cliente lo maldigan todas las noches antes de acostarse, incluya un montón de código de ejemplo probado que realice algunas primitivas funcionales de alto nivel. Asegúrese de que los ejemplos no sean solo fragmentos de código, sino que estén completos y sean compilables o ejecutables desde el primer momento.

Tradicionalmente, los escritores tecnológicos han distinguido entre manuales de referencia y guías de usuario . El manual de referencia generalmente incluye las especificaciones de sintaxis, una definición inteligible de las funciones o primitivas, la discusión de los gotcha, el rendimiento y los efectos secundarios, y un breve ejemplo de uso. La guía del usuario incluye ejemplos de uso más extendido y una discusión sobre cuestiones de ingeniería más amplias. El "Lenguaje de programación C" de Kernigan y Ritchie es un excelente contraejemplo de esta convención, pero este enfoque solo funciona cuando el lenguaje que está documentando es relativamente simple.

El autor fue gerente de la División de Servicios de Ingeniería en el centro de desarrollo de Ready Systems Inc entre 1987 y 1991 con la responsabilidad de administrar un equipo de cinco escritores de tecnología.