Техническая документация и документация по разработке программного обеспечения

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

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

До сих пор я читал о типе документации, и, похоже, что техническая спецификация и документация по разработке программного обеспечения - это те, которые предоставляют такую ​​информацию.

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

Например, здесь , в нем говорится, что Документация по разработке программного обеспечения используется для предоставления команда разработчиков программного обеспечения общего руководства по архитектуре программного проекта . И здесь говорится, что Техническая документация используется для новый разработчик, который присоединяется к программному проекту. Какая информация была бы полезной для ознакомления с проектом?

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

2 голоса | спросил MrRobot 1 J000000Sunday18 2018, 22:45:59

2 ответа


5

Что такое техническая документация?

Настоящее определение: Техническая документация означает любой документ, который обычные смертные не понимают из-за некоторых требуемых специальных знаний.

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

Какова цель вашей документации?

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

  • Это для новых членов ? Самое главное - дать обзор (например, архитектура и слои, основные компоненты), модель домена высокого уровня (т.е. контекстная карта ), а также некоторые руки по информации (например, структура каталогов, используемый набор инструментов, соглашение об именах, ссылка на другие важные документы для чтения). Детали будут в любом случае быть в коде, будь то в понятном чистом коде или полезных комментариях.
  • Это для пользователей библиотеки ? Ваш javadoc или doxygen создадут подходящую справочную документацию, основанную на комментариях, которые встроены в ваш код (поэтому, надеюсь, легко поддерживать). К сожалению, эта подробная информация не позволит легко понять дизайн вашей библиотеки. Опять же, вам нужно предоставить некоторый обзор высокого уровня в архитектуре библиотеки и как его различные компоненты взаимодействуют и зависят друг от друга. Такая документация ДОЛЖНА ИМЕТЬ, если ваша библиотека является коммерческим продуктом, проданным самостоятельно.

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

Некоторые советы

Грэди Буч опубликовал в своей книге «Объектно-ориентированный анализ и технику проектирования», содержание требуемой документации по программному обеспечению:

  
  • Архитектура систем высокого уровня
  •   
  • Ключевые абстракции и механизмы в архитектуре
  •   
  • Сценарии, иллюстрирующие построенное поведение ключевых аспектов системы.
  •   

Далее он сделал очень конкретный момент:

  

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

ответил Christophe 2 J000000Monday18 2018, 00:41:32
3

Существует два основных вида документации: руководство пользователя и справочная документация .

(Некоторые компании также рассматривают обзор как отдельный вид, см. ниже.)


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

  • Обратите внимание на интерфейс public : его основная цель - указать, какие детали наблюдаемого поведения официально гарантированы и, таким образом, можно опираться. (Указывая или подразумевая, что все остальное является деталями реализации, может быть изменено и разорвано без предупреждения.)
  • Также обратите внимание на слово "wholety". Основной точкой продажи ссылки является ее полнота. Если это не в ссылке, оно не существует (официально). Если я прочитал ссылку на тему, я могу быть уверен, что теперь я знаю все на эту тему, и неприятных сюрпризов не будет.
    • Итак, хотя ссылка может быть использована в качестве учебного материала, его основным вариантом использования является заполнение пробелов.

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

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

A Руководство пользователя - это скорее продемонстрировать, как авторы продукта предполагают использование публичного интерфейса для решения практических задач и /или их классов: предполагаемые шаблоны использования, типичные общие проблемы и предлагаемые решения (проблемы локальные к конкретным API, похоже, скорее принадлежат в своих ссылочных позициях).

Руководство пользователя намеренно неполно, предоставляя только «большую картинку» и указатели на клавиши и оставляя их до ссылки на подробные сведения.

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

  • обратите внимание на слово . Это рекомендация: «Это тот способ, которым мы намереваемся быть предпочтительным». То, что может (или не может) быть вызвано, откуда прямой домен документации.

Некоторые компании, например. Microsoft, разделяют обзор наивысшего уровня на отдельный вид документации. Во многих местах MSDN вы увидите раздел X, разделенный на: «О X», «Использование X» и «Ссылка X».


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

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

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

    /li>
Страницы

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

ответил ivan_pozdeev 2 J000000Monday18 2018, 01:57:44

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132