Un escritor de API es un escritor técnico que escribe documentos que describen una interfaz de programación de aplicaciones (API). La audiencia principal incluye programadores, desarrolladores, arquitectos de sistemas y diseñadores de sistemas.
Descripción general
Una API es una biblioteca que consta de interfaces, funciones, clases , estructuras, enumeraciones, etc. para construir una aplicación de software. Los desarrolladores lo utilizan para interactuar y ampliar el software. Una API para un lenguaje o sistema de programación dado puede constar de construcciones definidas por el sistema y definidas por el usuario. A medida que aumenta el número y la complejidad de estas construcciones, se vuelve muy tedioso para los desarrolladores recordar todas las funciones y los parámetros definidos. Por lo tanto, los escritores de API juegan un papel clave en la creación de aplicaciones de software .
Debido al tema técnico, los escritores de API deben comprender el código fuente de la aplicación lo suficiente como para extraer la información que requieren los documentos de API. Los escritores de API a menudo usan herramientas que extraen la documentación de software colocada por los programadores en el código fuente de una manera estructurada, preservando las relaciones entre los comentarios y las construcciones de programación que documentan.
Los escritores de API también deben comprender el producto de software y documentar las nuevas funciones o cambios como parte de la nueva versión del software. El calendario de lanzamientos de software varía de una organización a otra. Los escritores de API deben comprender bien el ciclo de vida del software e integrarse en el ciclo de vida de desarrollo de sistemas (SDLC).
Los escritores de API en los Estados Unidos generalmente siguen el Manual de estilo de Chicago en cuanto a gramática y puntuación . [ cita requerida ]
Calificaciones
Los escritores de API suelen poseer una combinación de habilidades de programación y lenguaje; muchos escritores de API tienen experiencia en programación o redacción técnica .
- Experiencia en programación informática (conocimiento de C , C ++ , Java , PHP u otros lenguajes de programación )
- Conocimiento de estándares de formato como Doxygen , Javadoc , OpenAPI o DITA
- Conocimiento de editores y herramientas, como FrameMaker.
- Excelentes habilidades de comunicación y redacción para interactuar con los desarrolladores.
Los escritores expertos de API / kit de desarrollo de software (SDK) pueden convertirse fácilmente en escritores de programación .
Proceso de escritura de API
El proceso de escritura de la API generalmente se divide entre analizar y comprender el código fuente , planificar, escribir y revisar. A menudo ocurre que las etapas analítica, de planificación y de redacción no se producen de forma estrictamente lineal.
Los criterios de redacción y evaluación varían de una organización a otra. Algunos de los documentos de API más efectivos están escritos por aquellos que son capaces de comprender adecuadamente el funcionamiento de una aplicación en particular, de modo que puedan relacionar el software con los usuarios o las diversas construcciones de componentes con el propósito general del programa. Los escritores de API también pueden ser responsables de la creación de la documentación del producto del usuario final .
Si bien la documentación de referencia puede generarse automáticamente para garantizar que esté completa, la documentación que ayude a los desarrolladores a comenzar debe ser redactada por un redactor de API profesional y revisada por expertos en la materia. [1] Esto ayuda a garantizar que los desarrolladores comprendan los conceptos clave y puedan comenzar rápidamente.
Producto
Los escritores de API producen documentos que incluyen:
- Guías de referencia de API
- Guías de programadores
- Manuales para desarrolladores
- Manuales de administración
- Guías de instalación
- Guías de implementación e integración
Ver también
Referencias
enlaces externos
- Documentación de API: redacción de documentación para desarrolladores para API y SDK de Java
- Cursos gratuitos de escritura técnica de Wikiversity
- Biblioteca de comunicación técnica (y redacción técnica) de EServer
- ¿La muerte del autor técnico?