Какие инструменты используются для написания документации?
В частности, для
- Документы пользователя
- Системное администрирование
- Разработка
Я ищу программное обеспечение таких MS Word, wiki, TeX (LaTeX, LyX) и для автоматизированных инструментов.
Какие инструменты используются для написания документации?
Ответ 1
Я пишу в Markdown, тот же синтаксис форматирования, который мы используем в Stack Overflow. Поскольку документы представляют собой простой текст, они могут жить вместе с кодом в управлении версиями. Это полезно.
Я переношу документы в HTML и PDF с помощью швейцарского армейского ножа Pandoc. С небольшой таблицей стилей они выглядят лучше, чем документы из текстовых процессоров.
Если мы говорим о технической документации, на мой взгляд, есть два отдельных вида документации, из которых вы должны иметь оба. Для библиотек и API существует автоматическая документация, описывающая вызовы функций и типы, которые полезны для справки, но вам также нужна прозаическая документация по стилю руководства/учебника, которая может быть прочитана сверху вниз:
- Pandoc ссылка на API низкого уровня для хакеров
- Pandoc прокси-руководство пользователя для пользователей (и хакеров)
Добавление. Вы можете использовать Sphinx для обеих видов документации. Выход красивый
https://readthedocs.org/ поможет вам начать работу с Sphinx и разместить сайт для вас
Ответ 2
Недавно я обнаружил Dr. Объясните, что отлично подходит для создания документации пользовательского интерфейса. Он входит и разбивает все элементы пользовательского интерфейса (кнопки, элементы меню, поля редактирования и т.д.) Из вашего запущенного приложения, а затем извлекает любую метаинформацию, которую он может от них, для начала вашей документации (см. Снимок экрана). Тогда все, что вам нужно сделать, это удалить или настроить элементы, которые он нашел, и редактировать описания. Очень быстро создает действительно профессиональную документацию по пользовательскому интерфейсу. Он также имеет все другие функции документации для поддержки конечных пользователей, которые вы ожидаете.
Этот снимок экрана показывает вам одно из изображений, которые он создает для вас. Это было создано, указав его в окне настроек. Затем он добавляет маленькие пронумерованные синие квадратики в видимые элементы управления пользователя. Он также извлекает информацию о типе и контроле типа (кнопка, флажок и т.д.), А также другую метаинформацию. Эти изображения также можно сделать кликабельными, чтобы разрешить сверление с экрана.
Эта функция действительно сдула меня. Это может быть не лучше всех, но эта функция была довольно удивительной.
Ответ 3
Мы всегда предпочитали LaTeX, потому что наши документы имеют массу тяжелой математики... Но, что более важно, это простой текст, что означает, что с VCS (CVS, SVN, Git и т.д.) это очень легко справляется.), и он может легко жить прямо там с кодом - так что нет оправдания для того, чтобы не обновлять документацию по мере развития.
Как кивок Кристоферу, мы довольно исследовательская организация (хотя и не .edu)...
Ответ 4
Я использую Visio для создания документов и временных графиков UML. Для меня все это делается во время дизайна, когда я пытаюсь понять, как я хочу, чтобы все было организовано или как все должно работать. Затем (надеюсь) они обновляются после того, как реализация выполнена так, чтобы они соответствовали тому, что было сделано (реализация никогда не соответствует дизайну!).
Для документации кода я использую несколько инструментов, в зависимости от языка. Все это использует вариации комментариев в стиле javadoc, которые мне нравятся.
Visual Studio имеет встроенный инструмент документации для С# (и, возможно, других языков .Net), который использует комментарии, подобные XML. Я считаю, что другие упомянули об этом.
Для остальной части нашей документации (Сетевой протокол и т.д.) мы используем корпоративную Wiki. Мы используем Confluence, хотя есть много вариантов Wiki. Мы считаем, что использование wikis является весьма полезным, так как легко для любого обновить документы, когда это необходимо, а также легкодоступно (без прохождения файлов Word).
Ответ 5
К сожалению, я обычно застрял, используя блокнот.
Ответ 6
С С# и .Net у нас есть комментарии к XML-коду, которые скомпилированы в файлы справки, используя Sandcastle.
Для пользовательской и системной документации у нас есть Wiki - в частности Confluence.
Ответ 7
Для написания документации для конечных пользователей необходимо рассмотреть много вещей, прежде чем вы начнете смотреть на какой-либо конкретный инструмент. К ним относятся:
- Каковы ваши требования к инструменту? Это может включать "контент, доступный в веб-браузере в виде HTML" или "просмотр содержимого в офлайн-режиме как CHM", или оба.
- Вам нужен инструмент, чтобы быть достаточно простым, чтобы кто-нибудь из вашей команды мог его использовать, или у вас есть специальный технический писатель, который проведет весь свой день в приложении?. Сначала требуется простое приложение, которое делает для вас большую часть работы. Второй требует мощного, гибкого приложения с множеством функций.
- Какая будет лучшая презентация вашего контента? HTML, wiki, форум или что-то еще?
Ответ на эти вопросы поможет вам сравнить ваши варианты инструментов.
Ответ 8
Confluence и JavaDoc здесь. Слияние для нестандартных материалов, таких как архитектура, инструкции, трюки, образцы кода, некоторые сообщения об ошибках и т.д. И т.д.
Если он специфичен для проекта и не подходит для JavaDoc, я просто добавляю файлы с открытым текстом *.txt к проектам в качестве поддерживающей документации. До сих пор он работал нормально.
Ответ 9
Это еще один отличный инструмент для документации, который полностью свободен для личного использования.
Ответ 10
Здесь мы используем:
- Word - для создания большинства документов
- Visio - для создания диаграмм, а также каркасов
Ответ 11
Мы используем Wiki of Fogbugz для общей документации и SandCastle для API.
Ответ 12
Мы также используем Sandcastle и GhostDoc, но для UML-материалов на платформе Windows я не нашел ничего лучшего в "свободной" ценовой категории, чем StarUML.
StarUML - это огромное значение. Развитие, похоже, застопорилось последние 3 года, но это замечательно стабильный инструмент. Я использовал другие халявы (например, ArgoUML), но они не так быстро или полнофункциональны. Это не замена хорошего коммерческого инструмента, но в большинстве мест, где я работал, никто не хочет выкладывать деньги на что-то вроде Enterprise Architect.
Ответ 13
Для пользовательских документов и большинства других форм документации я чаще всего использую MS Word.
Для документации по разработке, особенно к документам API, такие инструменты, как Javadoc и Doxygen, используются много. Вики тоже хороши.
Я не вижу, чтобы TeX или LaTeX много использовали вне академических или исследовательских сообществ.
Ответ 14
Мы входим в wiki (media wiki) для всего: от дизайна до документов конечного пользователя, а также документов, подробно описывающих наши лабораторные установки, и кто использует какие машины. Материал конечного пользователя импортируется в acrobat и генерируется в приятный PDF файл для пользователей (и я думаю, что реальные бумажные документы все же). Мы используем Borland Together для моделирования UML (и генерации кода, но это другое сообщение). Мы указываем нашим тестировщикам на wiki, когда они идут, чтобы протестировать новую функцию, а затем они также могут писать ошибки как с документами, так и с продуктом. Сначала я был настроен скептически, когда мы начали это делать (у нас были писатели, с которыми мы будем работать), но стали большим поклонником. Кажется, нашим пользователям это нравится.
Ответ 15
Пару людей уже упомянули документацию на С# xml, а другие упомянули doxygen для C/С++/Java, но я хотел бы напомнить всем, что он также поддерживает документацию по стилю С#. Он может создавать документацию в html, postscript, pdf и man-страницах, поэтому вам не нужно зацикливаться на файлах справки Sandcastle.
Ответ 16
Word и Visio, очевидно, являются стандартными инструментами де-факто. Но чтобы сделать их действительно полезными для технической документации, у вас должны быть очень хорошие шаблоны, которые упрощают форматирование. Чем меньше вы должны думать об этом, тем больше вы можете думать о содержании. Я использую документ Word с множеством заданных стилей... вещи, такие как заголовки разделов, форматирование тела, списки, блоки кода и т.д.
В Visio я использую стандартный набор Shapes для каждого типа диаграммы, которую я хочу создать (системная диаграмма высокого уровня, пользовательский интерфейс, рабочий процесс и т.д.).
Я действительно очень горжусь своим шаблоном Word. Это очень чисто. Я отправлю его всем, кто хочет получить копию.
Ответ 17
Если вы предпочитаете специальный редактор для латекса, я бы предложил texmaker (для linux), или вы могли бы просто пойти с emacs;)