Как делать документацию к программе

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

Цель лекции: ознакомиться с видами программных документов и основными правилами оформления программной документации.

Одним из главных отличий программы от программного продукта является наличие разнообразной, хорошо подготовленной документации. Составление программной документации — важный процесс. На каждый про­граммный продукт должна разрабатываться документация двух типов: для пользовате­лей различных групп и для разработчиков. Отсутствие документации любого типа для конкретного ПО не допустимо. При подготовке документации не следует забывать, что она разрабатывается для того, чтобы ее использовали, и потому она должна содержать все необходи­мые сведения [1].

К программным относят документы, содержащие сведения, необходи­мые для разработки, сопровождения и эксплуатации программного обеспе­чения. Документирование программного обеспечения осуществляется в со­ответствии с Единой системой программной документации (ГОСТ 19.ХХХ). Так ГОСТ 19.101-77 устанавливает виды программных документов для ПО различных типов.

Исполнительная документация легко!

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

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

Следующим по важности документом является программа и методика испытаний (ПМИ). Структурно она подобна ТЗ – практически для каждого пункта ТЗ в ПМИ говорится, как этот пункт будет проверяться. Способы проверки могут быть самыми разными – от пропуска специального теста до изучения исходных текстов программы, но они должны быть предусмотрены заранее, а не придумываться в момент испытаний. Новички приступают к составлению ПМИ непосредственно перед завершением работ, а опытные руководители составляют и согласовывают с заказчиками одновременно с ТЗ. Хорошо составленная ПМИ является гарантией успешной сдачи работ.

Как документировать код | Doxygen урок

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

Руководство оператора (пользователя) – это основной документ, описывающий, как пользоваться системой [16]. В хорошем руководстве сначала описывается идея системы, основные функции и как ими пользоваться, а уже потом идет описание всех клавиш и меню.

Руководство программиста — это самый объемный документ, описывающий внутреннюю организацию программы. Обычно этот документ идет в паре с документом » текст программы » – одностраничным документом с оглавлением дискеты или CD. Руководство программиста дает заказчику возможность дописать новые фрагменты программы или переделать старые.

В современной литературе этот документ называется SDK (Software Development Kit). Продукт, снабженный SDK, может стоить на порядок дороже, чем такой же продукт без него. Сейчас не принято продавать исходные тексты программ – проблемы с интеллектуальной собственностью, даже при наличии SDK трудно «влезть» в чужую программу – как говорится, себе дороже.

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

Наличие множества API, конечно, хуже, чем наличие исходных текстов (например, нельзя переделать что-то в середине функции), зато много проще в использовании. С другой стороны, все большую популярность приобретает FSF (Free Software Foundation). Основателем этого движения был Ричард Столман [4], который забил тревогу по поводу попыток крупных фирм запатентовать многие основные алгоритмы и программы: «Дойдет до того, что они запатентуют понятия «цикл» и «подпрограмма», что мы будем тогда делать?» FSF представляет собой собрание программ в исходных текстах; любой программист может свободно использовать их в своих целях, но все добавления и улучшения, которые он сделал, тоже следует положить в FSF. Таким образом, FSF представляет собой одно из самых больших доступных хранилищ программ.

Дополнительную информацию по теме можно получить в [1, 4, 16].

Понравилась статья? Добавь ее в закладку (CTRL+D) и не забудь поделиться с друзьями:

Источник: studopedia.ru

10 инструментов для безупречного документирования кода

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

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

• Ваш код будет поддерживаться и использоваться другими программистами в команде? Обслуживание кода становится большой проблемой, если он не был должным образом документирован.
• Вы хотите чтобы другие программисты помогли вам, например, через открытый исходный код. Если вы планируете начать большую, коллективную работу, стоит начать документирование кода прямо сейчас!
• Документирование вашего кодa делает логику гораздо более ясной, а также делает ваш код лучше.
• Недокументированный код тяжело не только передавать на сопровождение, а также порой тяжело сопровождать и самому

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

Эти инструменты помогут вам с документированием кода и в целом помогут стать на ступеньку выше. Давайте начнем!

DOXYGEN

Doxygen является отличным инструментом для генерации документации из исходного кода. Инструмент нацелен на документирование программного обеспечения, написанного на языке C++, однако на самом деле данная система поддерживает гораздо большое число других языков, таких как: C, Objective-C, C#, PHP, Java, Python, IDL, Fortran, VHDL, Tcl, и частично D. С помощью Doxygen, вы можете создать онлайн HTML документацию. Doxygen — консольная программа в духе классической Unix. Она работает подобно компилятору, анализируя исходные тексты и создавая документацию.

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

SPHINX

Sphinx это популярный инструмент позволяющий создавать текстовые документы и преобразовывать их в различные форматы. Это удобно при использовании систем управления версиями, предназначенных для отслеживания изменений. Он доступен по лицензии BSD и поддерживает несколько языков программирования, таких как Python, C и C++. Он может быть использован как для проектной документации так и для документации кода. Sphinx избавляет от рутинных действий и предлагает автоматическую функциональность для решения типовых проблем, например, индексирования заголовков и специального выделения кода (например, при включении в документ фрагментов кода) с соответствующим выделением синтаксиса.

PANDOC

Pandoc не похож на другие инструменты для документации. Он действует как швейцарский нож и позволяет разработчику быстро конвертировать разметку из одного формата в другой. Pandoc имеет широкий спектр поддержки документов, в том числе textile, reStrcuturedText, LaTex, EPUB и т.д.

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

DR. EXPLAIN

Frontend разработка также, в определенной степени, требует документирования. Создавать документацию как для обычных, так и онлайн-приложений, написанных на любом языке программирования, в любой среде разработки, с применением любого фреймворка поможет DR. EXPLAIN. Он фильтрует ключевые элементы интерфейса, а затем извлекает связанные с ним мета данные. После этого, вы можете изменить полученную информацию, чтобы быстро создать документацию интерфейса.

LATEX

LaTex является де-факто стандартом для документирования научных проектов. Тем не менее, он также может быть использован для других типов проектов, в том числе кода и проектной документации. Готовя свой документ, автор указывает логическую структуру текста (разбивая его на главы, разделы, таблицы, изображения) и позволяет LaTeX’у заботиться о том, как изобразить его.

MARKDOWN

Markdown, творение Джона Грубера, очень простой и изящный синтаксис разметки текста, который поможет вам писать качественный код и документации. С технической точки зрения Markdown является инструментом преобразования текста в HTML для веб-писателей, но в равной степени он может быть использован и для документирования. Как разработчик, вы можете написать документацию в Markdown, а затем использовать Pandoc, чтобы преобразовать его в любой формат, который вам нужен.

GHOSTDOC

GhostDoc это расширение для Visual Studio, с помощью которого вы можете легко генерировать комментарии документа XML. Инструмент генерирует комментарии на основе нескольких факторов, в том числе имя, параметры, контекстную информацию, типы и т.д.

NATURAL DOCS

Natural Docs это еще один инструмент с открытым исходным кодом, который работает со многими языками программирования. Он поможет вам автоматизировать генерацию документации кода и преобразовать его в формат HTML. В настоящее время NATURAL DOCS поддерживает 19 языков программирования, среди них Python, C ++, PL / SQL, Actionscript и т.д.

PHPDOCUMENTOR

Если вы PHP разработчик и хотите сгенерировать документацию кода из исходного кода, стоит рассмотреть PhpDocumentor. В основе работы системы лежит парсинг логической структуры PHP кода (классы, функции, переменные, константы) и привязка к ней комментариев, написанных по определенным стандартам. Инструмент также может помочь вам генерировать отчеты и графики и повысить общее качество кода.

LIVEEDU.TV

Как стриминговая платформа может помочь в документировании кода? Вы можете транслировать или хранить проектную работу непосредственно на Livecoding. Вы будете иметь возможность легко открыть доступ к важным разделам проекта для членов вашей команды. Несколько преимуществ использования видео в качестве инструмента для документирования кода. Некоторые из них приведены ниже:

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

Дамиан Вольф расскрывает данную тему боле подробно в статье “Why Developers Write Horrible Documentation and How to Solve It”.

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

Источник: educationecosystem.com

Управление документацией в проектах разработки ПО

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

Один из стереотипов, бытующих в среде российских и зарубежных разработчиков программного обеспечения, — отношение к проектной документации как к второстепенному атрибуту, замедляющему и бюрократизирующему работу. Вместе с тем многие стандарты и модели качества, такие как ISO 9000, CMMI и COBIT, уделяют значительное внимание документации, а многие последователи различных «скорых» методик, напротив, отводят документации минимум места в своих проектах. Разумный оптимум, как обычно, находится посередине.

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

Классификация и виды документации

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

Рисунок. Виды документации

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

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

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

Планы

Необходимыми атрибутами планов являются: собственно описание требуемых действий; информация о событиях, «запускающих» эти действия; описание взаимной зависимости действий между собой; информация об исполнителях. Календарный план (schedule), кроме этого, содержит информацию о прогнозируемых датах начала и окончания действий. Наиболее распространенным видом планов является план-график проекта в нотации Ганта и Перта.

Исследовательские проекты, а также проекты, управляемые временем (time-driven project), могут обходиться без планов-графиков. В таких проектах планирование может иметь неглубокий горизонт, а планы на будущий период фиксироваться, например, в регулярных отчетах.

Теория разработки программного обеспечения (в частности, модель CMMI) также упоминает множество других планов, которыми должна сопровождаться разработка: план управления требованиями, план управления изменениями, план управления рисками, план управления конфигурациями, план тестирования и т.д. На практике в «одиночном» проекте, не носящем большой сложности, большинство из этих планов могут носить самый общий характер и ориентироваться скорее на правила взаимодействия с заказчиком, чем на описание внутренних операций.

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

Задания исполнителям и отчеты о ходе работ

Задания (task), выдаваемые исполнителям, подлежат документированию в целях исключения их «забывания» и двоякого толкования. Документальные формы, используемые для накопления и отслеживания заданий, на практике используются редко и обычно в качестве источника информации о выданных заданиях применяются: планы-графики; специально выделенные разделы в регулярных отчетах; задачи, выставленные через Microsoft Outlook или через системы управления изменениями (такие, как IBM ClearQuest).

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

Протоколы

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

Отчеты о результатах активностей

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

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

Журналы

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

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

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

Технические требования

Технические требования, или требования к системе (system requirements specification), описывают функциональность, которую должен содержать продукт, а также ожидания заказчика относительно производительности, отказоустойчивости, надежности системы, среды, в которой она должна работать и т.д. Часто требования являются частью контрактной документации.

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

Технические спецификации

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

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

Сведения о выпуске

Сведения о выпуске (release note) описывают фактически реализованную функциональность и ошибки, исправленные в данном выпуске системы, а также различные особенности выпуска: среду, в которой продукт тестировался, отклонения от требований, неисправленные ошибки и т.д. В некотором смысле они представляют собой отчетный документ, так как от каждого выпуска заказчик ожидает определенных свойств и качества.

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

Руководства

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

Документация, методологии и стандарты качества

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

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

Источник: www.osp.ru