Что именно включает в себя «Документация»?

Когда мы говорим «документация» для программного продукта, что это включает и что не должно включать?

Например, недавно был задан вопрос, считаются ли комментарии документацией?

Но есть много других областей, для которых этот вопрос также является действительным, некоторые более очевидные, чем другие:

• Руководства (очевидно)
• Примечания к выпуску?
• Учебники
• Комментарии
• Любые другие?

Где проведена линия. Например, если «учебник» - это документация, документация «видеоруководство» или это что-то еще?

Как правило, что-то в программном обеспечении не «сделано», пока оно не будет реализовано, протестировано и задокументировано. Отсюда возникает вопрос, что мы должны рассматривать как часть документации, чтобы считать что-то «выполненным».

_{Вопрос вызвал недавние отзывы клиентов на нашей конференции, свидетельствующие о том, что нашему документу требовалось больше «образцов», о которых мы раньше думали не так хорошо, как следовало бы.}

_{Аудитория: разработчики программного обеспечения, использующие нашу базу данных (базы данных), языки программирования и соответствующие инструменты (такие как клиенты администратора для указанной БД)}

Цель документации - описать и объяснить программный продукт, чтобы вы могли определить документацию как набор артефактов, которые способствуют этому описанию или объяснению. Вы, вероятно, не рассматриваете связанные действия как часть документации: например, недельный учебный курс - это не документация, а материалы курса; пятиминутный чат на доске - это не документация, а изображение доски.

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

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

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

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

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

Некоторые факторы, которые вступят в игру:

• Вы разрабатываете программное обеспечение версии 1.0 и переходите от него к другим проектам или это долгосрочный проект? Комментарии / дизайн документов становятся гораздо важнее в последнем случае. С другой стороны, если ваш клиент - магазин пончиков для мамы и поп, и вы пишете для них веб-сайт, который вы никогда не увидите ... я думаю, документация по коду хороша, но не так важна.
• Вы разрабатываете мобильную игру или программное обеспечение, которое контролирует пульсометр в больнице. Угадайте, какое из них будет иметь определение «сделано», у которого гораздо больше документации?
• Ваши клиенты типичные конечные пользователи или они другие разработчики? У вас есть API / SDK, который вы выставляете?
• Каков уровень экспертизы ваших клиентов? Это влияет на выбор видео-учебника по сравнению с письменным материалом против какого-то интерактивного учебного приложения
• Ваши клиенты заботятся о том, что изменилось от версии к версии. Некоторые делают. Большинство не делает. Для немногих это закон (или близкий к этому), чтобы заботиться.

Документация - это материал, предназначенный для чтения без изменения.

Я думаю, что вы не ошибетесь с определением на основе цели ... но только если вы определите цель правильно.

• ^{Правильно определить цель документации не совсем просто. Простое (наивное, если хотите) различие, которое естественно приходит на ум, состоит в том, что документация - это все, что предназначено для чтения, а для сравнения код - это все, что предназначено для выполнения на компьютере . Звучит хорошо на поверхности, не так ли? но на самом деле все становится ужасно, когда вы копаете глубже.
   
  Дело в том, что хороший код учитывает проблемы читабельности, а также правильность выполнения - это делает различие «читабельности» довольно бесполезным при определении документации.
   
  Упомянутые вами образцы показывают, что с ним не так. Клиенты обычно ожидают, что они будут четко написаны ивыполнить правильно. Нарушение читабельности или правильности может привести к появлению жалоб клиентов. Наивное различие не помогает понять, являются ли примеры кодом или документацией.
   
  Использование наивного различия станет еще более запутанным, если вы представите себе работу с открытым исходным кодом . Вы загружаете, собираете и запускаете его - вы не читаете его, это просто код, верно? Подождите, что-то пошло не так, и вы попали в код, чтобы прочитать, что там происходит ... эй, вы читаете, не выполнить - эта документация сейчас? И, наконец, вы находите ошибку в исходном коде и исправляете ее - теперь это действительно код, это не то, что обычно называется документацией, независимо от того, насколько внимательно вы прочитали это, чтобы сделать это исправление.}

Для «образцов», которые вы собираетесь предоставить, различие «чтение-не-изменение» может оказаться весьма важным.

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

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

Все, что отвечает на вопрос «как мне ...», является документацией.

Для разработчиков это означает спецификации требований («как я знаю, что написать»), проектную документацию («как я отвечаю на мои требования»), матрицы прослеживаемости («как я узнаю, что мой проект отвечает всем моим требованиям»), планы тестирования («как я знаю, что мой код работает»), модульные тесты («как я узнаю, что я удовлетворен требованием X»), встроенные комментарии («как мне убедиться, что следующий бедный schlub понимает, почему я написал это путь »), инструкции по развертыванию (« как упаковать этот продукт для установки ») и т. д.

Для пользователей это означает руководства пользователя («как мне использовать программное обеспечение»), учебные пособия («как мне использовать эту особую функцию»), заметки о выпуске («как я узнаю, какие ошибки были исправлены / были добавлены новые функции ошибок»). добавил ") и т. д.