На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- СкуммВМ
- Технический писатель:
- б-джентльмен
- Название проекта:
- Улучшите документацию исходного кода с помощью Doxygen.
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
Текущая документация по ScummVM API (исходный код) опубликована здесь: https://doxygen.scummvm.org/modules.html.
К сожалению, во многих областях этого не хватает:
1) В нем практически нет структуры, вся информация плавает на одном уровне.
2) Элементы C++ документированы непоследовательно, а некоторые из них вообще не документированы. Это то, что организация называет одной из главных проблем.
3) Устаревший и устаревший контент по-прежнему отображается в выходных данных.
4) Язык и использование тегов doxygen должны быть более последовательными. Для этого необходим набор правил, который мог бы стать основой для будущего руководства по стилю документации для этого проекта.
5) CSS doxygen, используемый на этой странице, может быть улучшен, чтобы сделать его более похожим на веб-сайт ScummVM: https://www.scummvm.org
Все эти проблемы можно решить в рамках проекта «Сезон документации».
Это приложение Season of Docs сопровождается черновиком PR, который я открыл в проекте, чтобы продемонстрировать некоторые потенциальные улучшения, которые я предлагаю: https://github.com/scummvm/scummvm/pull/2361. Подробную информацию о том, что он содержит и для просмотра различий.
Примерно вот что включает в себя PR:
1) Я думаю, что сейчас больше всего сбивает с толку потенциальных новых участников и вообще всех, кто просматривает текущий документ API, — это отсутствие структуры. Внедрение структурированной документации API улучшит читаемость, находимость и, следовательно, удобство использования набора документации. Вот почему мой PR вводит группы doxygen для всех заголовочных файлов в «общей» папке. Благодаря этой новой структуре, если кто-то захочет найти документацию по API, связанному с ОС (например), он сможет легко найти ее в навигации.
2) Создан новый файл конфигурации doxygen, позволяющий создавать эту документацию.
3) Файл «links.doxyfile», из которого все ссылки, используемые в наборе документации, могут быть взяты из одного источника. Полезный механизм при работе с doxygen.
4) Модифицированный CSS doxygen. В настоящее время это взято из другого проекта с открытым исходным кодом и является лишь отправной точкой. В идеале внешний вид страницы doxygen должен более или менее соответствовать веб-странице ScummVM.
То, чего PR не охватывает, но над чем определенно нужно поработать, — это сам контент. Под этим я подразумеваю выявление существенных частей кода, которые не документированы, тех, которые недостаточно документированы, или устаревших частей кода, которые следует удалить из документации. Поскольку я раньше не работал в этом проекте, для достижения этой цели потребуется руководство наставника.
Конечно, реализуем ли мы что-то из пиара – это вопрос обсуждения с организацией. Моя идея заключалась в том, что действия говорят громче, чем слова, поэтому я решил показать, на что я способен, а не просто описывать это в приложении.
Организация предоставила следующий примерный график реализации этого проекта: Неделя Основная задача Неделя 0 (до 14 сентября) Обсуждение и анализ предложений Неделя 1 (14 сентября) Настройка сборки Doxygen Неделя 2 (21 сентября) Обновление скина Doxygen ( низкий приоритет) Неделя 3 (28 сентября) Общий код — OSystem, FS, структуры данных, строки и т. д. Неделя 4 (05 октября) Общий код — продолжение Неделя 5 (12 октября) Механизмы — Общий код и образец механизма Неделя 6 (19.10) Неделя графики 7 (26.10) Неделя аудио 8 (02.11) Видео, изображения Неделя 9 (09.11) Серверные части — платформы, графика, события Неделя 10 (23.11) Серверные части — продолжение недели 11 (11/30) Краткое описание и подача проекта
Единственное изменение, которое я бы предложил, — это начать с работы над структурой, как уже упоминалось. Это можно сделать в течение первой и второй недель вместе с настройкой сборки doxygen (которая в основном уже выполнена) и обновлением скина Doxygen. После этого я согласен, что имеет смысл пройтись по различным областям одну за другой вместе с наставником, чтобы выявить проблемы и улучшить документацию doxygen.
Я считаю, что это проект стандартной длины, но я уверен, что есть и другие улучшения, связанные с документацией API, которые можно будет внести после завершения проекта GSoD. Например, разработать руководство по стилю документации и добавить его в вики, чтобы участники знали, как им следует документировать добавляемый ими код.
Я бы с радостью помог с такими задачами после завершения GSoD. Я уверен, что ScummVM могла бы нанять технического писателя, который позаботится о том, чтобы ее документация по API была хорошего качества и удобства использования. Я также вижу, что есть и другие будущие проекты документации, в которых я мог бы вам помочь, например, создание руководства по работе с плагинами.