Ответ 1

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

Таким образом:

• У вас есть встроенное отслеживание изменений (при условии, что у вас есть достойная вики)
• Вы можете редактировать из любого места
• Каждый человек всегда видит одну и ту же документацию (мгновенное распространение)
• Вы можете сосредоточиться на содержимом вместо форматирования.

Ответ 2

Моим решением было потратить некоторое время на создание приличного шаблона Word для себя.

Важно, чтобы убедиться, что у вас есть стиль, определенный для всего, что вы можете поместить в документ.

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

Более широкая проблема заключается в том, что каждый человек проводит часы в Word, и все же очень редко компании вкладывают средства в обучение Word. В какой-то момент вам придется укусить пулю и потратить время, чтобы научить себя, как правильно ее использовать, так же, как и с любым другим инструментом.

Ответ 3

Все, что вы можете сделать с LyX, вы можете делать с LaTeX. LaTeX подходит для всех видов вещей; он использовался для всего, начиная с пособий и заканчивая лекциями слайдов для романов.

Я думаю, что LaTeX, вероятно, стоит рассматривать как вариант; если вы когда-либо хотели "закодировать" для вашего текстового процессора, LaTeX для вас. На простейшем уровне вы можете определить новые команды, чтобы делать что-то для вас, но там много силы. Результат выглядит очень аккуратно.

По моему мнению, LyX фантастичен в определенных обстоятельствах, удобен в других, а иногда просто мешает вам. Я думаю, что это следует рассматривать как ускоритель производительности для LaTeX. Другими словами, научитесь использовать LaTeX перед тем, как попробовать LyX. Оба они, конечно, бесплатны и доступны для Windows, хотя кривая обучения довольно крутая по сравнению с MS Word. Для длинных документов или большого количества подобных документов LaTeX/LyX, вероятно, стоит инвестиций.

Ответ 4

Вы можете написать свою документацию, используя свой собственный формат XML, а затем преобразовать ее в любой формат с помощью XSL (например, PDF через FOP + XSL-FO). См. Также DocBook формат XML.

Ответ 5

LaTeX - чрезвычайно мощный инструмент и может быть переполнен здесь, поскольку он предназначен для научной/математической литературы. У этого есть (относительно) крутая кривая обучения и может быть хитрым, чтобы коаксировать делать точно так, как вы хотите, если вы новичок в этом. Я ЛЮБЛЮ LaTeX, но это не действительно текстовый процессор общего назначения.

Вы рассматривали OpenOffice вместо этого?

Ответ 6

LaTeX - действительно очень мощный язык, если вам нужно писать документы.

Возможно, вы можете попробовать texmaker, кросс-платформенный редактор LaTeX:

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

Ответ 7

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

Ответ 8

Несмотря на все усилия и разумные ожидания, я не думаю, что Word Processing была "решена".

Мой ответ на то, что я лично лично считаю глубоко разочаровывающим в MS Word, - это вообще отказаться от него и использовать инструмент автоматической документирования, например GhostDoc до генерировать XML из того, что я уже написал в коде (DRY!), и обрабатывать XML с сайта интрасети на основе XSLT или аналогичного позже.

Ответ 9

Вы говорите о документировании своего реального кода? Если это так, я рекомендую Doxygen для неуправляемого кода и Sandcastle для управляемого кода. Оба будут собирать вашу помощь или создавать ее как веб-сайт для вас.

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

Ответ 10

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

Отвечайте на вопрос chris о моем рабочем процессе: я пишу документацию с помощью приложения в виде блокнота (TextWrangler, только из-за его функция обертывания слов) в своем необработанном формате Markdown. Затем у меня есть небольшой сайт документации по локальному хостингу с мой модифицированный анализатор Markdown (расширенный для нескольких функций и немного больше функций, ориентированных на HTML), который проверяет метки времени для файлов документации - если файл был обновлен, он анализирует этот файл в HTML и сохраняет файл в кеше.

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

Ответ 11

Ну, я никогда не обнаружил ничего плохого в MS-Word. (т.е. если вы потратите время, чтобы знать, как эффективно использовать его). OpenOffice действительно является удивительной и надежной альтернативой - но если вы ненавидите MS Word для проблем с компоновкой, то такая же проблема возникнет с OpenOffice тоже.

Никогда не пробовал систему Latex, но слышал ее полезность для научной работы. Я думаю, что использование какого-либо HTML-редактора WYSIWYG будет лучше для вас, если вы хотите просто сосредоточиться на контенте.

Ответ 12

У меня еще нет возможности попробовать это, но я всегда думал, что AsciiDoc будет хорошо для такого типа вещь.

Ответ 13

Если вам нужно что-то более простое, чем LaTeX, вы можете посмотреть ReStructured Text

Ответ 14

Прочтите эту книгу: http://en.wikipedia.org/wiki/The_Pragmatic_Programmer. Внутри есть исправление idee, так что документация должна быть построена автоматически. Подумайте об использовании своей IDE для этого или найдите дополнительные инструменты. Большинство современных языков поддерживают создание документации при написании кода. Это может просто поддерживать ваш документ в контакте с последними изменениями в коде.

Ответ 15

Вы можете посмотреть в doxygen на http://www.stack.nl/~dimitri/doxygen/, посмотреть их красивые примеры. В этом случае документация представлена ​​тегами в комментариях в источнике.

Другим вариантом будет использование онлайн-системы, такой как trac, из http://trac.edgewall.org/, которая является системой wiki/doc/issuetracking, которая живет вершина подрывной деятельности.

Ответ 16

Я предпочитаю использовать RTF-редактор, который намного менее clunkier чем слова. Таким образом, форматирование и все абзацы верхнего уровня не будут занимать половину вашего времени. Wordpad работал на меня несколько раз. На данный момент я придерживаюсь Word: (

Ответ 17

существует множество возможных способов:

• встроенная документация, например. javadoc: хорошо для описания API, не так хорошо для "большой картины".
• plain html: может быть проверен под контролем версий, определенный плюс
• wiki, например. confluence - отлично подходит для совместной работы, но имеет контроль версий, отличный от вашего источника.
• LaTeX или somesuch: лучше подходит для книг или документов, чем типичная документация; поддержка графики громоздка.
• клон Office, например. OpenOffice: в основном те же, что и Word + Visio, но с открытым исходным кодом, с более удобным форматом документов.

Я обычно документирую структуру программного обеспечения ( "метафоры" проекта, компонентные взаимосвязи, внешние системы) спереди, используя Visio, в "свободной форме" UML. Затем они встроены в слияние, которые могут быть преобразованы в PDF, если кто-то хочет распечатать.

Ответ 18

LyX

LyX является WYSIWYM front end to LaTeX: вы получаете удобство документального процессора (несколько похожего на Word) с последовательностью и мощностью LaTeX: он не мешает вам и может многое делать, что нужны профессиональным писателям.

Примечание: Правильный ответ для you действительно зависит от вашего мышления --- мы не можем решить это для вас. Этот ответ просто показывает отличный выбор, если вы думаете о документах как документах и ​​хотите что-то похожее на Word (где Word хорошо), что не сосать как Word (где Word плохо для программистов).

Но многие программисты думают о документации по-разному и, следовательно, предпочитают разные метафоры. У меня тоже была такая же проблема много лет назад, я работал с LaTeX (как я математик), нашел LyX и, наконец, обосновался в системе Wiki/Source, которую я написал сам.

Ответ 19

Vim - это решение для всего, что означает возможность написания простого текста наиболее эффективным способом. Если вам нужно форматирование, используйте XML, латекс или что-то подобное (в Vim).

Вим изменил мою жизнь!

Ответ 20

Простой ответ: LaTeX звучит как раз то, что вы ищете.

Я использую его для написания документации. Я никогда не вернусь к Word, если у меня есть возможность.

Ответ 21

В phc мы начали с латекса, затем перешли в docbook и решили (надолго надеюсь) на Restructured Text/Sphinx.

Латекс был выбран потому, что мы академики, а латекс - это инструмент выбора. Я считаю, что он не создал достаточно HTML.

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

Наконец, мы переместились в reST, используя sphinx, и это было отличное решение. Документацию теперь очень легко написать, и PDF и HTML версии выглядят красиво (хотя PDF файл может работать с некоторыми настройками). Его очень легко настроить тоже.

Лучший бит о reST, однако, заключается в том, что его читаемый человеком в исходной форме. Это замечательное преимущество. Я переключился на использование reST для всех моих вещей сейчас, особенно что-нибудь в Интернете (кроме, конечно, академических документов, где было бы глупо использовать что-либо, кроме латекса).