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

12

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

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

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

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

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

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


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

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

Дэн МакГрат
источник
2
Комментарии на downotes всегда приветствуются. К сожалению, цифры не дают много конструктивной критики, чтобы понять, где кто-то заблудился :)
Дэн МакГрат,
1
Документация по программному обеспечению или документация по исходному коду представляет собой письменный текст, сопровождающий компьютерное программное обеспечение. Он либо объясняет, как он работает, либо как его использовать, и может означать разные вещи для людей в разных ролях. - Ключевое предложение здесь «может означать разные вещи для людей в разных ролях», какова ваша аудитория? (Еще не проголосовали, но я предполагаю, что виновата неясность и открытость вопроса).
Яннис
2
Этот вопрос требует от кого-то нарисовать диаграмму Венна.
MathAttack

Ответы:

6

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

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

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


источник
Я считаю, что материалы курса являются документацией только в том случае, если они производятся / распространяются той же командой (в широком смысле), что и программное обеспечение. Абсолютно сторонние курсы не являются документами.
Donal Fellows
Конечно они есть. Сторонняя документация - это документация, даже если она не находится под вашим контролем (и вы не несете ответственность за ее создание): она служит цели читателя - объяснить им все, что нужно. Если для вас проблема в том, что люди пишут документацию, которая не находится под вашим контролем, вы должны устранить необходимость в этой документации.
2

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

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

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

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

  • Вы разрабатываете программное обеспечение версии 1.0 и переходите от него к другим проектам или это долгосрочный проект? Комментарии / дизайн документов становятся гораздо важнее в последнем случае. С другой стороны, если ваш клиент - магазин пончиков для мамы и поп, и вы пишете для них веб-сайт, который вы никогда не увидите ... я думаю, документация по коду хороша, но не так важна.
  • Вы разрабатываете мобильную игру или программное обеспечение, которое контролирует пульсометр в больнице. Угадайте, какое из них будет иметь определение «сделано», у которого гораздо больше документации?
  • Ваши клиенты типичные конечные пользователи или они другие разработчики? У вас есть API / SDK, который вы выставляете?
  • Каков уровень экспертизы ваших клиентов? Это влияет на выбор видео-учебника по сравнению с письменным материалом против какого-то интерактивного учебного приложения
  • Ваши клиенты заботятся о том, что изменилось от версии к версии. Некоторые делают. Большинство не делает. Для немногих это закон (или близкий к этому), чтобы заботиться.
DXM
источник
Сказать, что я принял неправильную часть разговора, основываясь на одном вопросе Q, - это немного большой вывод из одного вопроса :) Я новичок в этой компании и помогаю с улучшениями. Дать число наших «клиентов» в более чем 10 тысячах разработчиков (мы пишем базы данных), ведя переговоры с ними, все довольно сложно (хотя я стараюсь - создавать фокус-группы, консультативные советы и т.д.) Я не согласен с вашим ответом, но я просто искал то, что могло бы быть / не должно рассматриваться в документации для этой части разговора, поэтому у меня может быть точка отсчета, с которой можно начать, это не просто мое собственное мнение.
Дэн МакГрат,
@DanMcGrath: извините, я склонен тереть ПМ, в том числе и свой, неправильно. :) Независимо от предполагаемого вывода, который я сделал из вашего Q, я все равно утверждал бы, что "все", что идет вместе с кодом, может рассматриваться "документация". Если бы я был вами, вместо того, чтобы спрашивать «что может быть документацией» и составлять исчерпывающий список всех видов вещей (раньше у меня была справочная салфетка с диаграммой UML), я бы вернулся к своей клиентской базе и спросил им то, что им нужно. Если никто не говорит «Я хочу видеоурок», зачем мне тратить какие-то мозговые циклы, даже если учесть это?
ДХМ
Нет проблем ДХМ. Я тоже только новый премьер-министр, только недавно я бреюсь (частично). Мне было так интересно посмотреть, не вернулся ли кто-то с чем-то, что я не рассматривал ни как концепцию, ни как артефакт для рассмотрения. Я большой поклонник вопроса «в чем твоя проблема» и того, чтобы наша команда работала совместно с заказчиками, а не «что ты хочешь, чтобы мы делали». В том же духе, что и [«Мы хотим двигаться быстрее» -> Мы строим машины] против [«Мы хотим, чтобы вы давали нам более быстрых лошадей»]. Наличие у нас много информации помогает коллективно найти лучшее решение с большей вероятностью.
Дэн МакГрат
2

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

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

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

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

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

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

комар
источник
2

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

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

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

Джон Боде
источник