Использование систем для разработки технической документации
При написании спецификаций для внутреннего использования среди разработчиков, где не нужно соблюдать определенные стили, конечно, быстрее и легче всего пользоваться текстовым редактором или генератором из кода на усмотрение команды. Единственное необходимое условие – возможность просмотра истории изменений.
Если же вами создается коммерческий программный продукт для использования в определенной сфере, клиент ожидает увидеть документацию с хорошей структурой, удобным поиском, списком терминов. Также к вам может поступить запрос клиента на документацию, которая будет удобно прилагаться к продукту, например, быть встроенной в его интерфейс, или же на ссылку на онлайн-документацию в интерфейсе, а то и на справку для чтения в электронных книгах.
В своей работе я практически не опираюсь на существующие зарубежные стандарты по написанию технической документации, и тем более на ГОСТы, а стараюсь как можно больше взаимодействовать с клиентом или бизнес-аналитиками на стороне разработки и как можно тщательнее собирать требования к документации — к ее структуре, содержанию и внешнему виду. Документация ПО тем лучше, чем меньше нужно тратить на нее времени пользователю. Создавать документы, содержание которых не нужно листать часами, и в которых все, что нужно, находится на главной странице, и позволяют системы, с которыми я работаю.
Наиболее плотно мне довелось работать с Adobe RoboHelp – одной из самых первых и самых глобальных по функционалу систем документирования, а также MadCap Flare – продуктом, который создала некогда покинувшая Adobe группа разработчиков, которая учла все недочеты RoboHelp и снабдила Flare очень удобными опциями, о которых технические писатели, работавшие в других системах и не додумывались.
Подобные системы позволяют строить Help в форматах HTML, HTML5, CHM, PDF, Word, Ebook, и так далее. Обе системы позволяют держать всю документацию в одном проекте и собирать многочисленные её варианты с помощью из одного и того же источника. В этом и заключается принцип разработки документации на основе единого источника.
Преимуществ у таких приложений над текстовыми редакторами и системами, генерирующими код для описания, масса:
Если же вами создается коммерческий программный продукт для использования в определенной сфере, клиент ожидает увидеть документацию с хорошей структурой, удобным поиском, списком терминов. Также к вам может поступить запрос клиента на документацию, которая будет удобно прилагаться к продукту, например, быть встроенной в его интерфейс, или же на ссылку на онлайн-документацию в интерфейсе, а то и на справку для чтения в электронных книгах.
В своей работе я практически не опираюсь на существующие зарубежные стандарты по написанию технической документации, и тем более на ГОСТы, а стараюсь как можно больше взаимодействовать с клиентом или бизнес-аналитиками на стороне разработки и как можно тщательнее собирать требования к документации — к ее структуре, содержанию и внешнему виду. Документация ПО тем лучше, чем меньше нужно тратить на нее времени пользователю. Создавать документы, содержание которых не нужно листать часами, и в которых все, что нужно, находится на главной странице, и позволяют системы, с которыми я работаю.
Наиболее плотно мне довелось работать с Adobe RoboHelp – одной из самых первых и самых глобальных по функционалу систем документирования, а также MadCap Flare – продуктом, который создала некогда покинувшая Adobe группа разработчиков, которая учла все недочеты RoboHelp и снабдила Flare очень удобными опциями, о которых технические писатели, работавшие в других системах и не додумывались.
Подобные системы позволяют строить Help в форматах HTML, HTML5, CHM, PDF, Word, Ebook, и так далее. Обе системы позволяют держать всю документацию в одном проекте и собирать многочисленные её варианты с помощью из одного и того же источника. В этом и заключается принцип разработки документации на основе единого источника.
Преимуществ у таких приложений над текстовыми редакторами и системами, генерирующими код для описания, масса:
- Вы можете «собирать» одну и ту же документацию в разном формате. Например, однажды ваш клиент изменит свои требования и попросит онлайн Help в формате HTML5 вместо PDF. Для технического писателя займет не больше часа времени получить соответствующий результат.
- Возможность форматировать текст как с помощью готовых опций вроде возможностей в MS Word, так и самостоятельно делая изменения в HTML и CSS.
- Множество переменных с различными функциями. Вы можете использовать один и тот же фрагмент текста в разных местах, всего лишь «перетащив» его переменную в нужное место в тексте. Также вы можете создать переменную с номером новой версии продукта, и она автоматически обновится во всей документации.
- Наличие в вашей документации удобного поиска, индекса и словаря.
0 комментариев