На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- OpenMRS.org
- Технический писатель:
- летучий мозг7
- Название проекта:
- Документация OpenMRS REST API
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
Я разобью свое предложение на различные разделы и буду следовать последовательности действий, например, документации по API Google Maps и документации по API Github.
Помимо этого, я также хотел бы предложить структуру readme для документации API, созданную Realworld.io: https://github.com/gothinkster/realworld/tree/master/api .
Лично мне эта документация показалась очень простой для понимания и использования.
Мое предложение в основном будет состоять из 3 разделов:
Раздел, в котором будет дано краткое представление об API, об OpenMRS, о том, как используется API, и о том, что из этого следует.
Как получить ключ API и аутентификацию, необходимую в целом для выполнения запроса API. Это будет пример типов аутентификации, присутствующих в API, а также ключей и значений, которые должны быть для него представлены, а также типов значений, которые принимаются в соответствии с ключом в этой части. Пример кода на любом языке поможет понять, как писать заголовки, форматы ответов и другие параметры запроса в API.
Следует упомянуть типы ответов, получаемых API, типы JSON или любые другие типы результатов, возвращаемых API.
Различные маршруты API и все параметры, которые необходимо отправлять вместе с ними, заголовки и многое другое. Каждый API будет сопровождаться примерами кода на нескольких языках, которые описывают, как выполняется запрос во время написания кода для него, кроме того, следует также упомянуть общие коды ошибок, которые могут возникнуть в каждом API.
Это общее представление о том, как будет определяться документация для REST API.
График реализации проекта следующий:
1 августа - 1 сентября
Познакомьтесь с моим наставником и обсудите более подробно уровень документации, требуемой в различных частях кодовой базы, а также обсудите, как более подробно углубляться в документацию низкого и высокого уровня. Я также потрачу это время на понимание кодовой базы и изучение концепций, чтобы лучше их документировать.
Неделя 1 и 2
Я буду обновлять и расширять руководство для участников. Я улучшу документацию по сборке исходного кода. Я также добавлю раздел документаторов о том, как новые участники могут помочь в документации. Я изучу различную документацию по API, начну с введения и добавлю аутентификацию для API.
Неделя 3–8
Я добавлю маршруты и ответы API, а также несколько примеров кода для каждого типа API (могут быть похожие типы API).
Недели 9 и 10
Добавьте структурирование документации API с помощью ссылок, т. е. связанного индекса для длинной документации API, и разделите ее по различным признакам, таким как разделы кода, обзор, параметры, корневые конечные точки.
Последняя неделя
Я использую последнюю неделю для подготовки итогового отчета о работе, проделанной за 12-недельный период документации. Я также потрачу это время на просмотр и доработку документации.