MS Word является злым! Существует ли хорошая альтернатива? [закрытый]

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

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

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

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

LyX

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

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

Но многие программисты думают об этом. документации по-разному и, следовательно, предпочитают разные метафоры.

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

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

есть много возможных способов:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

I considered a wiki, but I decided to go with a modified Markdown notation, for the simple reason, that a wiki's content isn't easily exported and distributed outside of the wiki itself, while the Markdown can be rendered into HTML.

Answer to chris' question about my workflow: I write the documentation with a Notepad-like application (TextWrangler, only because of its word-wrapping feature) in its raw Markdown format. Then I have a small localhost documentation website with my modified Markdown parser (extended for a few features and a bit more HTML-oriented functionality) that checks for the timestamps for the documentation files - if a file has been updated, it parses that file into HTML, and stores the file in a cache.

This way I'm able to edit the source documentation on my desktop, and just press F5 in my browser to see the results immediately.

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

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

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

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

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

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

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

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

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

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

At phc, we started with latex, then moved to docbook, and have settled (permanently I hope) on Restructured Text/Sphinx.

Latex was chosen because we are academics, and latex is the tool of choice. I believe it didn't generate good enough HTML.

Docbook was chosen for power, but it was very unwieldy. It put us off writing any documentation: code had to be manually formatted, we kept forgetting the syntax, and it was difficult to read. The learning curve was also steep.

Finally, we moved to reST, using sphinx, and that was a great decision. Documentation is now very easy to write, and both PDF and HTML versions look beautiful (though the PDF could do with some customization). Its very easy to customize too.

The best bit about reST though, is that its human readable in source form. That is a wonderful advantage. I've switched to using reST for all my stuff now, especially anything over the web (except of course academic papers, where one would be foolish to use anything but latex).