Что я подразумеваю под документацией?

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

В каких случаях стоит писать документацию?

Обобщая, можно сказать, что всегда, когда над проектом работает или планируется, что будет работать не один разработчик. В общем случае не важно, будут ли они работать последовательно или одновременно.

Зачем вообще писать документацию?

Для себя. По прошествии времени случается, мы забываем нюансы архитектуры. В случае больших проектов постоянное ворошение кода может быть накладно.

_{Работая над Chromium в LGE, у меня был специальный блокнотик, где я зарисовывал архитектуру модулей, над которыми турдился.}

Для коллег. Соглашусь, есть много талантливых ребят, которые могут и поднимают проекты в одиночку, но в общем случае «один в поле не воин». Для того чтобы избежать постоянных расспросов, намного эффективнее подготовить FAQ и документацию.

Для будущей поддержки. Представим, вашей команде передали объемный проект без документации. Конечно же, контактов авторов у вас нет. Как вы думаете, какая будет первая задача от руководства? На мой взгляд, следует уважать коллег – заранее подготовить описание передаваемого проекта. Когда-то и вы получите проект «в наследство».

Документация!

Чтобы не просто описывать сферического коня в вакууме, время от времени я буду ссылаться на реальный пример небольшого проекта «выходного дня».

Постановка цели

Решение задачи начинается с постановки цели. Цели создания нашей документации:

• ввести коллегу в курс дела;
• отобразить архитектуру проекта;
• обосновать использованные подходы;
• показать способы использования.

Можно считать, что мы добились успеха, если для понимания архитектуры не нужно открывать код.

Вводная часть документации

Понимание аудитории

Можно выделить два типа аудитории:

• пользователи;
• разработчики.

Пользователям необходимо понять, как воспользоваться вашим проектом для решения своих задач. Разработчикам интересны внутренности проекта в целях его улучшения. Документация сильно зависит от понимания того, для кого мы ее пишем.

_{Аудитория нашего примера - разработчики.}

Описание проекта

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

_{В проекте «выходного дня» мы преследуем две цели: 1) повысить уровень знаний разработчиков за счет изучения подходов, используемых в проекте; 2) предоставить готовый набор «черных ящиков» для быстрого создания своей собственной игры.}

Настройка и первый запуск

Что необходимо сделать, чтобы запустить ваш проект на машине пользователя? На что обратить внимание? Какие опции запуска и настройки окружения существуют?

Часто, особенно в проектах с открытым исходным кодом, подобную информацию выносят в файл README. На мой взгляд, было бы здорово включить ее и в документацию, добавив как можно более детальное описание различных вариаций настройки и запуска.

Часто задаваемые вопросы

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

Если вы не знаете, какие вопросы могут возникнуть у использующих ваш проект людей, я рекомендую составить список вопросов, освещающих базовые темы, не вошедшие в раздел описания проекта или раздел настройки окружения. В завершение добавьте несколько «продвинутых» примеров, наглядно демонстрирующих всю мощь проекта.

Поддержка

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

Архитектура проекта

Дав экскурс по настройке и основным элементам проекта, необходимо рассказать об архитектуре в общем виде:

• список всех главных модулей;
• их описание;
• диаграмма отношений модулей.

Получив эту информацию, пользователь должен ответить на следующие вопросы:

• Из каких подсистем состоит проект?
• Что делает каждая подсистема?
• В каких отношениях состоят эти подсистемы?
• Какие подсистемы можно отнести к основным (то есть к ядру)?
• Какие подсистемы можно отнести к вспомогательным (то есть, убрав которые, проект продолжит работать)?

Если, на ваш взгляд, представленной информации недостаточно для ответа, попробуйте конкретизировать ее.

Следующий аспект архитектуры – интерфейсы. Если в вашем проекте используются интерфейсы, перечислите их, дав краткую характеристику каждому. После прочтения человек должен ответить на следующие вопросы:

• Зачем интерфейс был создан (то есть какие задачи он решает)?
• Какую сущность он определяет (то есть почему именно этот набор методов)?
• В каких случаях следует наследовать интерфейс?

Далее, следует привести перечень опорных классов проекта. Опорные классы, в моем понимании, – это классы (или их наследники), с которыми вы работаете большее количество времени. Описание класса должно включать:

• имя класса;
• описание назначения класса (то есть зачем вы его вообще создали, какие задачи он решает);
• описание назначения основных методов;
• в каких случаях стоит его использовать;
• каким образом его использовать (например, есть ли нюансы в случае многопоточного приложения).

Это и есть те вопросы, на которые человек должен ответить после прочтения документации по каждому классу.

Способы использования

Программирование – наука прикладная: понимая, как запустить код, и то, как он устроен в базовом виде, скорее всего, пользователь захочет «потрогать проект руками». Добавьте в вашу документацию минимально необходимые примеры использования.

_{В контексте разбираемого проекта предоставить пример использования достаточно накладно – пришлось бы создавать несколько сцен, демонстрирующих работу каждой подсистемы. Думаю, в будущем мы так и сделаем, но сейчас для нас примером использования будет сам проект, то есть в документацию стоит включить конкретные примеры кода (например, инициализации, обработки реакций пользовательского интерфейса, игровой логики и т. д.).}

Прочитав данный раздел, человек должен ответить на следующие вопросы:

• Как создать минимальный запускающийся пример?
• Как настроить рабочее окружение?
• Какие параметры какому классу необходимы?
• Какие основные классы используются в проекте?
• Какие изменения стоит внести, чтобы решить свои задачи?

Рекомендации

В общем-то, этого, на мой взгляд, должно хватить. Все же хотел бы подчеркнуть несколько критично важных моментов.

Только по сути

Не пишите “воды”, пишите только по сути. Если, выбрав «опорный» класс, вы понимаете, что писать про него особо нечего, возможно стоит вообще удалить его из документации. Помните, главная задача документации – помочь человеку понять ваш проект быстрее. Лишние слова только осложнят понимание и отвлекут от чтения действительно важной информации.

Будьте конкретны и критичны к тому, что пишите!

Правильные вопросы

Самое главное при написании – ставить перед собой правильные вопросы. Например, нужна ли вообще документация вашему проекту?

Постарайтесь понять, какими вопросами задается человек, который 5 минут назад скачал ваш проект. Зачем он вообще его скачал? Что ему действительно нужно? Каким образом документация может ему помочь? Как сделать это эффективней? Ответив на эти вопросы, вы сможете создать лучшую именно для вашего проекта структуру документа.

Постарайтесь создать набор вопросов, на которые должен ответить человек после прочтения каждой секции документации. Попробуйте ответить на эти вопросы сами, основываясь лишь на информации представленной в разделе. Это поможет более критично оценить ваш труд.

Изображения

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

Примеры кода

Дополняя текст конкретными примерами, вы добавляете контекст: используя имена конкретных классов, человек в будущем сможет найти конкретные реальные применения в коде.

Настройка и использование Unity 3D

Unity 3D – сложный графический редактор игры. Как минимум в моем проекте ручная настройка сцены заняла большое количество времени. Уверен, если вы добавите в вашу документацию снимки экрана с правильной настройкой сцены, настройкой окружения, иерархии объектов в сцене, расположения графики по папкам и т. д., пользователи вашего проекта будут вам благодарны.

Да, не забудьте вставить содержание в начало документа для улучшения навигации.

Удачи!