Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
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
Dividiré mi propuesta en diferentes secciones y seguiré el flujo, como la documentación de la API de Google Maps y la de GitHub.
Además de estos recursos, también me gustaría proponer una estructura readme para la documentación de la API que realiza realworld.io: https://github.com/gothinkster/realworld/tree/master/api
Personalmente, esta documentación me pareció muy fácil de entender y usar.
Mi propuesta constaría principalmente de 3 secciones :
Una sección que ofrecería una breve introducción sobre la API, sobre OpenMRS y sobre cómo se utiliza la API y lo que sigue después de eso.
Cómo obtener la clave de API y la autenticación que se necesita en general para realizar la solicitud a la API. Será un ejemplo de los tipos de autenticación presentes en la API, las claves y los valores que deben estar presentes, además de los tipos de valores que se aceptan correspondientes a la clave en esa parte. Una muestra de código en cualquier idioma ayudaría y aclararía cómo escribir los encabezados y 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 qué todos los parámetros se deben enviar junto con esos, los encabezados y otros elementos. Cada API recibirá la asistencia de 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 los códigos de error generales que se podrían 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
Familiarízate con mi mentor y debate en mayor profundidad el nivel de documentación requerido en las diferentes partes de la base de código, así como el nivel de profundidad 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 de documentadores sobre cómo los nuevos colaboradores pueden ayudar en la documentación. Estudiaré la documentación de las diferentes APIs, 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 API similares).
Semanas 9 y 10
Agrega la estructuración de la documentación de la API mediante vínculos, es decir, un índice vinculado para la documentación extensa de la API, y divídelo aún más de manera diferente, como secciones de código, descripción general, parámetros y extremos raíz.
Semana final
Usaré la última semana para preparar mi informe final del trabajo realizado durante el período de documentación de 12 semanas. También dedicaré este tiempo a revisar y finalizar la documentación.