Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- OpenMRS.org
- Escritor técnico:
- batbrain7
- Nombre del proyecto:
- Documentación de la API de REST de OpenMRS
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Desglosaré mi propuesta en diferentes secciones y seguiré el flujo como la documentación de la API de Google Maps y la documentación de la API de GitHub.
Además de esto, también me gustaría proponer una estructura de readme para la documentación de la API que realiza realworld.io: https://github.com/gothinkster/realworld/tree/master/api
Personalmente, encontré esta documentación muy fácil de entender y usar.
Mi propuesta constaría principalmente de 3 secciones :
Una sección que brinde una breve introducción a la API, a OpenMRS y a cómo se usa la API y qué sigue después.
Cómo obtener la clave de API y la autenticación que se necesita en general para realizar la solicitud a la API Este será un ejemplo de los tipos de autenticación presentes en la API y las claves y los valores que deben estar presentes para ella, así como los tipos de valores que se aceptan correspondientes a la clave en esa parte. Una muestra de código en cualquier lenguaje ayudaría a aclarar cómo escribir los encabezados, los formatos de respuesta y otros parámetros de consulta en la API.
Se deben mencionar los tipos de respuestas que recupera la API, los tipos de JSON o cualquier otro tipo de resultado que devuelven las APIs.
Las diferentes rutas de la API y todos los parámetros que se deben enviar junto con ellos, los encabezados y otros elementos Cada API tendrá muestras de código en algunos lenguajes que describen cómo se realiza la solicitud mientras se escribe el código para ella, además de que también se deben mencionar los códigos de error generales que se pueden encontrar con cada API.
Esta es una idea general de cómo se definirá la documentación para la API de REST.
El cronograma del proyecto es el siguiente :
Del 1 de agosto al 1 de septiembre
Familiarizarme con mi mentor y analizar con más detalle el nivel de documentación requerido en diferentes partes de la base de código y también analizar qué tan detallado debo ser en la documentación de bajo nivel en comparación con la de alto nivel También dedicaré este tiempo a comprender la base de código y estudiaré los conceptos para poder documentarlos mejor.
Semanas 1 y 2
Actualizaré y extenderé la guía para colaboradores. Mejoraré la documentación sobre cómo compilar el código fuente. También agregaré una sección para documentadores sobre cómo los colaboradores nuevos pueden ayudar en la documentación. Estudiaré la diferente documentación de la API y comenzaré con la introducción y agregaré la autenticación para la API.
Semanas 3 a 8
Agregaré las rutas y respuestas de la API junto con algunas muestras de código para cada tipo de API (puede haber tipos de APIs similares).
Semanas 9 y 10
Agrega la estructuración de la documentación de la API con vínculos, es decir, un índice vinculado para la documentación extensa de la API y divídelo según distintas bases, como secciones de código, descripción general, parámetros y extremos raíz.
Última semana
Usaré la última semana para preparar mi informe final del trabajo realizado durante el período de documentación de 12 semanas. También aprovecharé este tiempo para revisar y finalizar la documentación.