Качественная документация – неотъемлемая часть успешного программного продукта. Создание полного и понятного описания всех функций и возможностей программы и программного компонента требует немало сил и терпения. В данной статье я рассмотрю некоторые практические аспекты создания документации для .NET компонентов.
Предположим, что у нас готова или почти готова некоторая .NET библиотека для разработчиков (они же конечные пользователи). API библиотеки безупречен, количество багов впечатляюще мало, да и вообще это не библиотека, а просто кладезь совершенного кода. Дело за малым – объяснить пользователям, как работать с этим замечательным продуктом.
Есть разные подходы к написанию документации. Некоторые команды предпочитают начинать создание документации в момент начала создания продукта. Другие откладывают написание мануалов на окончание работ. В некоторых командах документацию пишут специальные люди, которые ходят от разработчика к разработчику и от менеджера к менеджеру, аккумулируя знания о продукте. Во многих небольших командах таких специальных людей нет, а потому документацию часто пишет разработчик или разработчики. Кто-то использует сторонние средства вроде Help & Manual, в которых, как в заправском текстовом редакторе, можно создавать очень сложную верстку и на выходе получать документацию в многообразии форматов. Многие используют другой подход, широко пропагандируемый в последнее время – написание документации прямо в коде программы/библиотеки.
Генерируем файл документации
После того, как xml-описание вашего компонента готово, можно сгенерировать файл документации. Я предпочитаю для этого использовать связку Sandcastle + Sandcastle Help File Builder (SHFB). Замечу, что некоторым больше по душе DocProject. Для этого требуется:
Скачать и установить Sandcastle
sandcastle.codeplex.com/
Скачать и установить Sandcastle Help File Builder
shfb.codeplex.com/
Скачать и применить патч для стилей, используемых Sandcastle
sandcastlestyles.codeplex.com/
Если у вас возникнут проблемы со сборкой документации в формате HTML Help, то нужно проверить, что itircl.dll присутствует в системе и зарегистрирована. Обычно эта dll лежит в System32, регистрировать ее нужно через regsvr32. Подробнее написано тут:
frogleg.mvps.org/helptechnologies/htmlhelp/hhtips.html#hhc6003
Read more: Habrahabr
Предположим, что у нас готова или почти готова некоторая .NET библиотека для разработчиков (они же конечные пользователи). API библиотеки безупречен, количество багов впечатляюще мало, да и вообще это не библиотека, а просто кладезь совершенного кода. Дело за малым – объяснить пользователям, как работать с этим замечательным продуктом.
Есть разные подходы к написанию документации. Некоторые команды предпочитают начинать создание документации в момент начала создания продукта. Другие откладывают написание мануалов на окончание работ. В некоторых командах документацию пишут специальные люди, которые ходят от разработчика к разработчику и от менеджера к менеджеру, аккумулируя знания о продукте. Во многих небольших командах таких специальных людей нет, а потому документацию часто пишет разработчик или разработчики. Кто-то использует сторонние средства вроде Help & Manual, в которых, как в заправском текстовом редакторе, можно создавать очень сложную верстку и на выходе получать документацию в многообразии форматов. Многие используют другой подход, широко пропагандируемый в последнее время – написание документации прямо в коде программы/библиотеки.
Генерируем файл документации
После того, как xml-описание вашего компонента готово, можно сгенерировать файл документации. Я предпочитаю для этого использовать связку Sandcastle + Sandcastle Help File Builder (SHFB). Замечу, что некоторым больше по душе DocProject. Для этого требуется:
Скачать и установить Sandcastle
sandcastle.codeplex.com/
Скачать и установить Sandcastle Help File Builder
shfb.codeplex.com/
Скачать и применить патч для стилей, используемых Sandcastle
sandcastlestyles.codeplex.com/
Если у вас возникнут проблемы со сборкой документации в формате HTML Help, то нужно проверить, что itircl.dll присутствует в системе и зарегистрирована. Обычно эта dll лежит в System32, регистрировать ее нужно через regsvr32. Подробнее написано тут:
frogleg.mvps.org/helptechnologies/htmlhelp/hhtips.html#hhc6003
Read more: Habrahabr