Документирование программ Хабрахабр. На определенном этапе развития программной системы неизбежно возникает задача разработки пользовательской документации. И тут возникает технический вопрос выбора форматов и инструментов разработки документации. По умолчанию в дистрибутивах для Windows поставляются CHMфайлы. Для использования HTMLфайлов следует заменить CHMфайлы каталогами man при этом каталог manВыходные форматы. С выбором конечного формата обычно проблем не возникает, так как целевая операционная система предъявляет свои требования. Так, например, для программ для Windows это формат скомпилированной справки CHM, для Linux и BSD систем это man. Общим для всех систем форматом для онлайн справки является html, а для печати pdf. Ситуация осложняется в случае, если необходимо иметь документацию в нескольких форматах для распространения с программой chm или man, для размещения на сайте html и для печати pdf. Chm Editor Инструкция По Применению' title='Chm Editor Инструкция По Применению' />Far позволяет создавать файлы и папки с пробелами и точками в конце имени, с зарезервированными именами, с именами длиннее 260 символов, со всякими прочими странными символами в именах, а потом эти файлы не открываются в других программах из этих папок не запускаются. Установка MediaWiki занимает от 10 до 30 минут используя MySQL и включает в себя загрузку, копирование файлов, создание базы данных и пользователя и запуск программы установки для настройки программного обеспечения. Смотрите Инструкцию по установке, где вы также. При этом возможно, что содержание документации в различных форматах может несколько отличаться. Например, видеофрагменты имеет смысл включать в онлайн документацию, а в печатной версии их нужно заменять на статическое изображение, возможно дополненным qrcode ссылки на видеофрагмент. Кроме того, содержание документов может отличаться и для различных категорий пользователей, версий, комплектов поставки и других факторов. VLMi9utbKPQ/Tokhm6MBeLI/AAAAAAAAwug/q7LOpgtMs0U/s1600/mintinstall-app.png' alt='Chm Editor Инструкция По Применению' title='Chm Editor Инструкция По Применению' />Исходные форматы. Несмотря на кажущуюся очевидность необходимости использования специально созданных программ, здесь не все так однозначно. В зависимости от целевой операционной системы подходы отличаются. Проприетарные исходные форматы. Так, для создания скомпилированной справки для Windows в формате chm Microsoft предлагает использовать специальный бесплатный компилятор HTML Help Workshop. При этом исходные тексты должны быть подготовлены в формате html редактор в поставку не входит, а файлы оглавления в специфическом формате. Никаких средств формирования печатных руководств не предоставляется. Разумеется, специализированные программы для создания справки Robohelp, Help Manual, Help. Scribble и им подобные предоставляют высокий уровень сервиса, обладают возможностью формирования выходных документов в различных форматах и даже в некоторой степени профилировать содержимое. Однако им присущи следующие недостатки Во первых, все эти системы коммерческие и лицензируются по количеству используемых рабочих мест. Во вторых, используемый ими внутренний формат является проприетарным и не поддержимается никаким ПО, кроме продаваемого. Возможность импортировать файлы в проект вам, конечно, будет предоставлена, а вот экспортировать проект в какой либо открытый формат, пригодный для дальнейшей обработки, не удасться. CHM Editor портативный инструмент нового поколения, позволяющий работать с CHMфайлами. Упаковано с помощью WinRAR 5. Показать Скрыть текст. CHM Editor это отличный выбор для тех, кто. Описание каждой статьи начинается с указания topic id уникального идентификатора. На основе этого идентификатора генерируется html файл, который позже попадет в chm. Генерируемый htmlфайл именуется в форме TOPIC. Данный topic id используется также для ссылок. Перевод CHMфайлов. Быстрый поиск CHMфайлов. Архивариус 3000 4. Первый из них платный, а все остальные относятся к категории freeware либо бесплатны для некоммерческого применения, что вполне оправданно с позиции. Так, например, для программ для Windows это формат скомпилированной справки CHM, для Linux и BSD систем это man. Вместе с тем, для разработки программной документации больших систем следует применять в качестве исходного формата открытый, хорошо. Даже в случае использования в качестве внутреннего формата XML как, например, Help Manual схема его остается закрытой и никак не задокументированной. В третьих, возможности по изменению внешнего вида выходного документа являются недостаточными для формирования, например, документации в соответствиями с требованиями ГОСТ. В четвертых, с этими программами организовать коллективную работу если и возможно, то крайне затруднительно. Простые форматы разметки. Рациональной альтернативой представляется применение простых и, как следствие, быстро осваиваемых форматов разметок. На сегодняшний день таких форматов несколько ASCIIdoc, используемый дефакто в Linux BSD системах Wiki, применяемый в различного рода энциклопедиях и даже давший им общее название Mark. Down так сказать, многоцелевой формат документирования. Все эти разметки используют некоторый символьный нетеговый набор правил оформления заголовок, иллюстраций и ссылок, предполагающий редактирование в простых текстовых редакторах. Подготовка же пригодного к просмотру вида осуществляется программно как правило на стороне сервера. Например, Википедия преобразует Wiki формат в HTML на лету. Веб портал системы Git http github. Markdown в пригодном для чтения в браузере виде. Редакторы. Несмотря на то, что для создания и редактирования исходных текстов достаточно возможностей блокнота, некоторые сервисные функции, такие как проверка правописания и подсветка разметки были бы писателю весьма кстати. В статье http www. Одним из таких редакторов является Markdown. Pad. 1. 3. 1. Markdown. Pad. Рисунок 1. Редактор Markdown. Pad 2. Как видно из копии экрана, редактор Markdown. Pad 2 поддерживает живой предварительный просмотр редактируемого файла с поддержкой синхронной прокрутки исходного текста и результата рендеринга. При установке на Windows 8 может возникнуть ситуация, когда предварительный просмотр недоступен. Рисунок 2. Сообщение о крахе системы предварительного просмотра. По заявлению разработчиков http markdownpad. SDK веб рендеринга Awesomium 1. SDK, который в свою очередь использует Direct. X. Редактор поддерживает подсветку синтаксиса, проверку синтаксиса одного языка в том числе русского, экспорт в форматы HTML, PDF только в платной версии. Иными словами, Markdown. Pad 2, как и другие специальный редакторы, является хорошим выбором для технического писателя. В тех же случаях, когда пользователю предстоит редактировать файлы различного формата, можно адаптировать свой редактор и для редактирования текстов с markdown разметкой. Notepad. Редактором, в достаточной мере отвечающим этим требованиям, можно считать Notepad. Проверка правописания многих языков поддерживается с помощью специального плагина. Причем поддерживается проверка текста на нескольких языках одновременно. Рисунок 3. Редактор NotepadНесмотря на простоту правил разметки, автору текстов было бы удобней работать с подсветкой синтаксических элементов. Применительно к Notepad в этом поможет проект Markdown Syntax Highlighting for Notepad, который, по сути, представляет собой конфигурационный файл пользовательского языка Markdown. После его установки текст в редакторе выглядит следующим образом. Рисунок 4. Редактор Notepad с подсветкой элементов разметки markdown. Quota. Примечательно, что редакторы с поддержкой markdown существуют даже для мобильных платформ. На рисунке приведена копия экрана смартфона с запущенным редактором Quoda Code Editor. Рисунок 5. Quoda Code Editor универсальный редактор для Андроид с поддержкой разметки markdown. Следует сказать, что большая часть этой статьи набрана именно в этом редакторе, а уже потом выгружена на компьютер для доработки. По результатам анализа возможностей языка разметки Markdown и специальных редакторов можно рекомендовать их применение для документирования систем средней сложности. Открытые теговые форматы. Вместе с тем, для разработки программной документации больших систем следует применять в качестве исходного формата открытый, хорошо документированный формат. В качестве средства формирования инструмент с широкими возможностями по настройке внешнего вида, профилирования и способностью формировать документы в различных форматах. Этим требованиям в полной мере отвечают такие системы как DITA и Docbook. Создание документации в. NET Хабрахабр. Качественная документация неотъемлемая часть успешного программного продукта. Создание полного и понятного описания всех функций и возможностей программы и программного компонента требует немало сил и терпения. В данной статье я рассмотрю некоторые практические аспекты создания документации для. NET компонентов. Предположим, что у нас готова или почти готова некоторая. NET библиотека для разработчиков они же конечные пользователи. API библиотеки безупречен, количество багов впечатляюще мало, да и вообще это не библиотека, а просто кладезь совершенного кода. Дело за малым объяснить пользователям, как работать с этим замечательным продуктом. Есть разные подходы к написанию документации. Некоторые команды предпочитают начинать создание документации в момент начала создания продукта. Бытовая Травма Объяснительная Образец на этой странице. Другие откладывают написание мануалов на окончание работ. В некоторых командах документацию пишут специальные люди, которые ходят от разработчика к разработчику и от менеджера к менеджеру, аккумулируя знания о продукте. Во многих небольших командах таких специальных людей нет, а потому документацию часто пишет разработчик или разработчики. Кто то использует сторонние средства вроде Help Manual, в которых, как в заправском текстовом редакторе, можно создавать очень сложную верстку и на выходе получать документацию в многообразии форматов. Многие используют другой подход, широко пропагандируемый в последнее время написание документации прямо в коде программыбиблиотеки. Я в своей работе использовал и сторонние средства, и встроенные. Начинал писать документацию и сразу, и в последний момент. В итоге я для себя решил, что документацию лучше начинать писать во второй половине создания продукта, так как чем ближе к завершению, тем более стабилен API, набор возможностей и т. Написание документации прямо в коде тоже, в конечном счете, оказалось удобнее, чем в сторонних программах, хотя поначалу казалось совсем наоборот. Эта статья как раз о том, как писать документацию прямо в коде. Описываем API. Компиляторы C и VB. NET умеют распознавать комментарии, оформленные специальным образом xml комментарии и при необходимости создавать xml файл, который можно потом использовать для создания документации. Чтобы воспользоваться этой возможностью необходимо описать все публичные классы и методы с помощью xml комментариев. Выглядит это примерно так  lt summary  Gets the R component from ABGR value returned by  lt see cref. Его нужно включить в свойствах проекта на вкладке Build. В результате при компиляции, в дополнение к файлу вашей сборки, будет сгенерирован xml файл, который содержит все xml комментарии из кода в том числе комментарии к непубличным структурам. Этот файл уже сам по себе полезен тем, что если его положить рядом со сборкой вашей dll, то это позволит функции Intelli. Sense в Visual Studio отображать описания для методов в момент набора пользователем кода. Вот пример того, как это будет выглядеть для функции Get. R, показанной выше Однако в большинстве случаев сгенерированный xml файл содержит комментарии к внутренним структурам, которые пользователям не нужно или нельзя видеть. Ниже я напишу, как автоматически очистить xml файл так, чтобы в нем остались только описания к публичным методам. Я не буду подробно рассматривать все xml теги, а лишь попробую кратко описать наиболее часто используемые. Тег summary служит для краткого описания назначения класса, интерфейса, перечисления enum, методов и свойств класса или интерфейса и членов перечисления. Тег param позволяет описать параметр, принимаемый функцией. Этот тег нужно использовать для каждого принимаемого параметра. Тег returns используется для описания возвращаемого значения функции. Тег value полезен для описания значения, которое принимает иили возвращает некоторое свойство. В некотором смысле тег value является аналогом тега returns. Gets the font ascent. The font ascent. lt value  lt remarks Ascent is the maximum height above the baseline reached by glyphs in this font, excluding the height of glyphs for accented characters. Ascent. Этот тег можно использовать практически везде кроме описания членов перечисления. На самом деле для членов перечисления тоже можно, но в документации, оформленной в стиле vs. Приведу еще несколько практических замечанийрекомендаций. Скачайте и установите расширение для Visual Studio под названием Ghost. Doc. Это расширение работает во всех версия студии начиная с версии 2. По нажатию на Ctrl Shift D это расширение вставляет описание сущности, на которой в данный момент стоит курсор. Вставляются все необходимые теги, и генерируется текст описания на основе, например, названия метода и названия его параметров. Часто остается лишь откорректировать и дополнить сгенерированный текст. Недостаток написания документации прямо в коде в том, что комментариев порой больше, чем кода, что может сильно затруднять чтение кода. Для обхода этой проблемы очень удобным оказывается полное разделение публичного интерфейса и реализации. Если у вас есть несколько перегруженных методов, то при генерации документации для них будет создана отдельная страница вот пример такой страницы. Текст для этой страницы нужно указать в теге overloads в описании одного из перегруженных методов. Saves the font bytes to the specified stream. Частичную спецификацию и отсутствующий префикс можно использовать, например, для ссылок между двумя методами одного класса или между двумя сущностями одного пространства имен namespace. Пример использования частичной спецификации Pdf. Font. Embed. Style находится в одном пространстве имен с Pdf. Font public sealed class Pdf. Font. Примеры полной спецификации ссылка на свойствоlt see cref. Можно сэкономить ручной труд, если копировать полные спецификации из ранее скомпилированного xml файла. Со ссылками на группу перегруженных методов связана одна неприятность. Visual Studio требует, чтобы такие ссылки были вида O XXX. YYY, в то время как Sandcastle Help File Builder требует, чтобы такие ссылки были вида Overload XXX. YYY. Для решения этой проблемы я использую простой скрипт, который вызывается на Post build event и заменяет в xml файле O на Overload, что вполне терпимо. Для ссылки на некоторую внешнюю статью вашей документации не связанную с описанием API или на некоторый ресурс в Интернет используйте старый добрый тег lt a с атрибутом href. Например, lt a href. В первом примере имя документа с внешней статьей представлено в форме TOPIC. О том, что такое topic id, речь пойдет далее. Более глубоко ознакомиться с документированием кода с помощью xml комментариев можно в этих статьях Генерируем файл документации. После того, как xml описание вашего компонента готово, можно сгенерировать файл документации. Я предпочитаю для этого использовать связку Sandcastle Sandcastle Help File Builder SHFB. Замечу, что некоторым больше по душе Doc. Project. Для этого требуется Скачать и установить Sandcastlesandcastle. Скачать и установить Sandcastle Help File Buildershfb. Скачать и применить патч для стилей, используемых Sandcastlesandcastlestyles. Если у вас возникнут проблемы со сборкой документации в формате HTML Help, то нужно проверить, что itircl. Обычно эта dll лежит в System. Подробнее написано тут frogleg. Приступаем к сборке документации в формате chm.