Wiki для разработчиков технической документации

Руководство программиста

wiki → Руководство программиста  
Чтобы стать редактором Wiki оставьте заявку в произвольной форме на форуме 



С чего начать написание Руководство программиста? (обсуждение на форуме)

Цели и задачи 

Руководство программиста разрабатывают в трех случаях: 
программный продукт по своему основному назначению является средой разработки или библиотекой (как Delphi или Qt); 
комплекс или программный продукт служит платформой для разработки программ или систем определенного типа (как 1С или Axapta); 
программа распространяется вместе с исходным кодом или постоянно модифицируется самими разработчиками. 
Наверняка можно представить себе и другие ситуации (например, программный продукт является операционной системой), но в жизни они встречаются значительно реже. 
Очевидная задача руководства программиста — снабдить разработчика информацией, которой ему будет достаточно для создания на базе нашего программного продукта собственных программ или систем. Еще один мотив создания такого документа — потребность разработчиков время от времени фиксировать состояние продукта, чтобы самим в нем не запутаться и не плодить в коллективе носителей «сакральных знаний». 

Содержание документа 


Руководство программиста должно объяснять: 


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


В какой среде функционирует приложение или система? Какими будут его минимальные требования к системе? Понадобятся ли для его запуска какие-либо дополнительные программные средства: фреймворки, рантаймы, интерпретаторы. 


Что представляет собой минимальное работоспособное приложение или минимальная работоспособная система. Какие объекты в какой последовательности необходимо создать, и как их друг с другом соединить, чтобы приложение вывело хотя бы «Hello World». Правда, бывают приложения, которые вообще не выводят текста, а управляют доменной печью или трафиком в сетях, но у них все равно обязательно есть какой-то свой минимальный вывод. 


Как (по шагам) скомпилировать работоспособное приложение или развернуть работоспособную систему. 
Это основные вопросы, без ответов на которые программист не сможет нормально работать. Если не сообщить их ему в явном виде, он будет вынужден заняться исследованиями. Но есть еще много дополнительных: методика и техника отладки, стиль программирования и др. 
Кроме теории руководство программиста должно содержать полные описания всех предусмотренных в программном продукте объектов. Если это функции, то должны быть приведены их синопсисы, если классы, то описания их интерфейсов и т. д. 
Если программный продукт предполагает использование оригинального языка программирования и снабжен собственным компилятором или интерпретатором, в руководство программиста необходимо включить его описание. Однако, если оно получается достаточно объемным, его выносят в отдельный документ, который так и называется: описание языка (программирования). 


Методика и стиль изложения 


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


При описании объектов особое внимание следует уделять следующим аспектам: 
  • Что обязательно должно предшествовать созданию и использованию объекта.
  • Каковы побочные эффекты обращения к объекту.
  • Особенности интерпретации объектом передаваемых ему данных.
  • Где «физически» (в каком файле, в какой библиотеке) находится объект. 
Желательно по каждому объекту привести примеры использования, небольшие фрагменты кода, демонстрирующие: 
  • создание объекта (если перед использованием его необходимо создать);
  • передачу объекту входных данных;
  • получение выходных данных и их интерпретацию. 
Описания объектов можно вынести в отдельный том или документ под названием «Справочник программиста». Хорошая мысль — сделать его гипертекстовым. 
Между теоретической частью и справочником по объектам полезно поместить небольшой раздел, в котором рассматривается пример небольшого, но полноценного, с точки зрения используемой платформы, приложения. Пример должен быть таким, чтобы читатель смог самостоятельно это приложение воспроизвести, отладить и запустить. Очевидно, для этого сначала все это должен проделать кто-то из авторов руководства программиста. 

Типовая структура руководство программиста 

Структура руководства программиста, зафиксированная в ГОСТ 19.504-79, такова: 
  • Назначение и условия применения программы.
  • Характеристика программы.
  • Обращение к программе.
  • Входные и выходные данные.
  • Сообщения. 


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



Это нравится:0Да/0Нет

Зарегистрируйтесь