Новости технической документации: до победы ещё далеко

От переводчика: В марте 2019 года автор этого поста Juan Carlos G. Torres был нанят некоммерческой организацией KDE e.V. по краткосрочному контракту на роль специалиста по документации. В рамках этой работы Хуан Карлос оценивает состояние документации и составляет списки задач с приоритетами, чтобы при последующем найме технического писателя на длительный срок можно было заранее согласовать конкретный план работ.

Konqi в офисе — Tyson Tan для сообщества KDE.

Прошло около 3 месяцев с тех пор, когда я отправился на поиски приключений в то место, которое называется «документация для разработчиков». Хотя запланированный период для этой работы подходит к концу, на самом деле путешествие только начинается. Как и для первооткрывателей прошлого, первый важный шаг — обойти местность и составить карту для будущих исследователей.

Документация для разработчиков в сообществе KDE — строго говоря, не новая территория, но по прошествии многих лет она выросла из сада в огромный лес, с которым могут справиться только несколько смелых людей. Неплохо было бы им помочь.

Сообщество KDE призывает героев, чтобы собрать и упорядочить документацию для разработчиков (а в дальнейшем — также для пользователей). Нам нужны разные герои: от технических писателей и авторов документации до разработчиков — будь то новичков или опытных участников. Нам нужны разные глаза: свежие глаза, опытные глаза, глаза посторонних людей, глаза членов сообщества, чтобы лучше уловить, что разработчики ожидают увидеть в нашей документации.

Список предстоящих задач был бы очень длинным, но вот несколько из них, которые будут по силам людям с совершенно разными навыками и уровнями осведомлённости о KDE:

• Вычитка документации по API: документация по API — это профессиональная документация по KDE Frameworks и другим библиотекам для широкой аудитории читателей. Чтобы придать ей более профессиональный вид, можно начать хотя бы с поиска опечаток и грамматических ошибок. Бонусная миссия: убедиться, что документация по API соответствует политике документирования библиотек KDE.
• Вводные руководства: у KDE есть огромное количество статей-инструкций (tutorials) по работе с теми или иными технологиями, как для внешних разработчиков — на TechBase, так и для участников сообщества — на Community Wiki. Просто проверяя, работоспособны ли по-прежнему инструкции из этих статей, сразу можно понять, требуют ли они обновления.
• Информация о проектах и командах: KDE — место обитания многих программных проектов и команд, некоторых из которых прекратили существование. Помечая исчезнувшие проекты и обновляя информацию об активных проектах и командах, можно избавить от мучений новых участников, которые пытаются понять, с чего начать и с кем нужно взаимодействовать.

Основную массу это работы можно выполнять, не покидая вики-сайты KDE. Всё что вам нужно — это учётная запись KDE Identity, которая также проложит путь к другим форматам вашего участия в сообществе. KDE — прекрасное сообщество, которое создаёт прекрасное программное обеспечение. Всего лишь вопрос времени — когда мы завоюем признание за прекрасную документацию, и в стремлении к этой цели мы полагаемся на помощь всех.

Автор: Juan Carlos G. Torres

Перевод: Александр Поташев

Источник: https://jucato.wordpress.com/2019/05/27/kde-developer-documentation-update-far-from-the-endgame/