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

Часто ли у вас бывает так, что в процессе работы над каким-либо научным проектом, вам в голову приходит идея автоматизировать тот или иной этап исследовательской работы? Вроде: «почему бы не написать программу расчета фолдинга данных белков и в дальнейшем моделировать эксперименты, только изменяя параметры».

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

Решений видится несколько.

1. Не делать руководство пользователя вообще.

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

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

2. Заказать написание документации на стороне.

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

3. Создать документацию своими силами.

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

Свои сложности, конечно, есть и здесь:

• Действительно, вы ученый, а не технический писатель. В предельном случае – вы вообще никогда не писали документацию, и не знаете, как это делается. В более мягком варианте, вы знакомы с ЕСКД, но этого может быть недостаточно;
• В силу основного рода деятельности, уделять много времени написанию руководства вы не сможете. Скорее всего, оно будет создаваться «по остаточному принципу». А в таких условиях разбираться с новыми для себя инструментами тяжело и долго;
• Научный софт выглядит, за неимением лучшего слова, довольно-таки «научно». Документировать придется сложные экраны и формы с множеством полей, параметров и настроек.
• Также возможно наличие в тексте документации сложных формул, таблиц или форматирования.
• Очень часто в разработке научного ПО задействованы несколько человек. Следовательно, разные разделы документации тоже могут разрабатывать совершенно разные люди. Иногда находящиеся в разных городах или даже государствах.
• Может потребоваться публикация документации в разных форматах.

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

К счастью, все вышеперечисленные трудности легко преодолимы при использовании специализированных инструментов для создания пользовательской документации. Одним из таких инструментов является Dr.Explain - программа для создания документации.

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

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

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

Высокая скорость разработки документации

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

Автоматические аннотации и удобные нумерованные выноски

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

Вставка любых объектов, формул, графиков, таблиц и т.д.

Скажем просто: редактор в Dr.Explain позволяет создавать тексты любой сложности. Все, что можно создать в Word или Adobe Acrobat – можно создать и здесь.

Удобная совместная разработка

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

Легкая публикация в любом желаемом формате

Вы создаете документацию один раз. А опубликовать ее затем можно хоть в PDF, хоть в HTML, хоть на сайте выложить.

Заключение

Как видите, нет ничего сложного в разработке пользовательской документации для научного программного обеспечения своими силами. Весь вопрос в наличии под рукой правильных инструментов. И Dr.Explain (www.drexplain.ru) – именно такой инструмент.