Где отчет по загрузкам фиговины с хреновины за последний месяц? Мы его 26 секунд назад должны были послать! Заказчик в потолок кричит уже!

Или нет, лучше вот так:

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

Да не вопрос! Открыл новую вкладку в IDE, вдохновился и описал свой шедевр. Вернее, попытался описать. Диаграммку надо вот тут вставить, а вон там без скриншота не обойтись...

Так, добавляем нужные теги в файл, меняем его расширение в html. Все, готово! Еще надо в PDF? Ставим виртуальный принтер и печатаем на него. Как картинки поехали? Переносим написанное в Word или LibreOffice. Заказчик зубчиками недоволен? Данные для диаграмки поменялись? Скриншотик поменять надо?  А-а-а-а … Отвалите от меня! Все, нету больше документации! Вон остатки валяются, пусть технический писатель мучается, ему за это деньги платят!

Знакомо? Думаю да. Любой, кто прикасался к описанию чего-либо, готов часами материться от совместимости форматов, стилей, шрифтов и прочих ужасов. А если подобное надо делать регулярно и еще совместно с кем-нибудь...

Все, мощнейшая демотивация обеспечена. А это неправильно. Тут я пишу про обратное, поэтому нефиг тут. Будем исправлять ситуацию.

Итак, за основу я предлагаю взять asciidoc. Есть для всех платформ и четко следует unix-идеологии выполнять хорошо только одну задачу. На входе обычный текст, а на выходе, особенно с использованием других программ, что угодно: от разметки для какой-нибудь wiki до pdf. После краткого просмотра команд становится непонятно, а почему раньше этим не пользовался...

Взято отсюда:

http://blog.kaloshin.ru/2012/11/12/Задокументируй-ЭТО/

Еще ссылки:

http://iportnov.blogspot.ru/2011/03/asciidoc-docbook.html

http://habrahabr.ru/post/12903/

http://en.wikipedia.org/wiki/AsciiDoc

Онлайн генератор:

http://andrewk.webfactional.com/asciidoc.php

Используется в т. ч. издательством O'Relly.

От себя: неплохая вещь, удалось установить под Windows в Cygwin и прикрутить к Sublime Text. PDF удачно сгенерировался через dblatex.

А как вы документируете проект? Или у вас ситуация, описанная самом начале топика?

(2) И как мне эта программа поможет?

(3) - сходи по ссылкам, там все написано

По Госту - нет не пишу, так в описание краткий хистори лог, а в доке краткая инструкция по работе

(4) Ходил, так и не понял

AsciiDoc - Это утилита, которая конвертирует обычные текстовые файлы (использующие очень простую и интуитивную разметку) практически во что угодно (html, docbook, man, etc.).

Ну и ?

Какой то RTF формат по сути

Попробовал засунуть в онлайн генератор - бред нечитаемый получился

(8) - это не RTF

(10) Я знаю что это не RTF, я же на писал ПО СУТИ (!)

AsciiDoc - это язык легковесной разментки.

(11)  - суть разная, ты RTF сам ручками никогда не будешь писать

Вообщем это для каких то олдскульщиков времен ББС, которые все инструкции писали в текстовом файлеке

(12) RTF ТОже язык разметки

В качестве примера рассмотрим следующий код в формате RTF:

{\rtf1
Привет!
\par
{\i Это} некий
отформатированный {\b текст}.\par
End
}

wiki:Rich_Text_Format

Судя по описанию на хабре AsciiDoc делает тоже самое

(14) - внимательно читай еще раз первый пост. Ты когда нибудь в википедии редактировал статьи?

(15) - это не язык разметки.

(16) - и? Он что я потом буду делать с RTF?

(18) тоже что и буду делать с
http://blog.kaloshin.ru/wp-content/uploads/2012/11/for_asciidoc.png

запущу в специальном редакторе, который на выходе сгенерирует
http://blog.kaloshin.ru/wp-content/uploads/2012/11/result1.png

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

и возвращаясь к сабжу AsciiDoc не может "Скриншотик поменять надо? " в случае если я поменяю что-то в своем проекте. Максимум что он может это взять из папки скриншот и вставить, и этот скриншот я должен заранее положить и обновить



Поэтому спрошу у ТС еще раз "И как мне эта программа поможет?"

(19)  - генерировать PDF/HTML/CHM/ODT/DocBook/Latex и прочее.

Ты знаешь чем отличается wiki:WYSIWYG от wiki:WYSIWYM ?

(21) - у них разные принципы. С исходным текстом RTF работает не человек, а машина.

С языками упрощенной разметки - с текстом работает непосредственно человек.

(22) - в том, что у тебя таких проблем не будет.

Читай про принцип wiki:WYSIWYM

(24) Каких таких?

(25) - описанных в (0). Или ты ни разу в жизни не начинал писать в Word-е что-то сложнее простого письма?

(23) как я буду генерировать то, что у меня нет?

Т.е. программа НЕ ПОЗВОЛЯЕТ писать и вести документацию, максимум что она может из заранее определенного формата (текст), с заранее установленными метками собрать doc файл.
Но это у меня и 1С без проблем сможет сделать

(26) В текстовом файле? Нет, у меня для этого word есть, где я пишу и форматирую по принципу WYSIWYG, и мне в голову не приходилось держать в голове тэги и писать в текстовом файле, чтобы потом на основе этих тэгов программа радила форматированный документ

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

>с заранее установленными метками собрать doc файл.

Зачем собирать Doc файл, если пользователю нужно PDF для печати и HTML для онлайн?

и никакого отношения к документации и 1С вообще не имеет

(30) Затем что моему пользователю нужна бумажная инструкция и он чахать хотел в pdf она будет или в html

Затем что моему пользователю глубоко фиолетово к ниму по электронки придет doc, pdf или html

(29) - ты когда нибудь писал в Word-е 1000-чную документацию с таблицами, шемаи, графиками, скиншотами совместно с другими программистами? Ну и?

(31) - имеет

вся юникс диалогия валится на параметрах

(30) А если пользователь захочет в mp3, программа сможет? нет? ну значит фигня, а не программа. Не надо выдавать заурядный возможности за сверх фичи без которых нельзя жить

(34) Диплом писал. Сойдет?

(37) - я начинал писать. Закончил на первой странице, перешел на LaTeX.

И кстати многих ты знаешь тут на форуме которые нужно "1000-чную документацию с таблицами, шемаи, графиками, скиншотами совместно с другими программистами?" Я думаю по пальцам одной руки можно посчитать.

(38) типа такого http://z4.d.sdska.ru/2-z4-1454fc98-a87f-4c36-8acf-f18326aca252.jpg

(38) а почему не тех - не осилил ?

(36) - Алексей, вы не теме. Зачем при людях показывать собственную глупость.

(41) - лолчто?

(43) Вы полагаете латех это расширение теха ?

а чо бы сразу не писать в ПостСкрипте - там ведь точно будете знать и о начертаниях и прочих позициях ?

(45) - я ничего не полагаю. Я использую лишь современные и адекватные задаче инструменты.

Word на первой же странице вел себя неадекватно.

(46) современные??? Спасибо поржал

(45) -  вы имеете представление, для кого предназначается PostScript?

(46) странно, у моей дочи он вполне себя адекватно ведет
диплом по метрологическому обеспечению у автоматчиков

(47) - Вы можете предложить современную адекватную замену LaTex - т.е. для тех же задач, что и LaTex?

(48) можно узнать куда отправляет латех вывод ?

(50) А давай для начало определим круг задач LaTex

для полной совместимости вообще нужен анси, а не всякая байда

(52) Возможности системы, в принципе, не ограничены (из-за механизма программирования новых макросов). Вот список некоторых возможностей, предлагаемых стандартными макросами и теми, которые можно скачать с сервера CTAN:

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

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

(54) И что из этого не умеет word?

(54) а ничо, что это все присутствует даже в ворд 3.0 ?

(56) - и это он умеет на профессиональном уровне с предсказуемым результатом: ведь он изначально разрабатывался как система верстки для типографий, да?

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

(58) для типографий очень давно работает пейджмекер, так же визави
а для записулек с картинками не нужен карьерный самосвал

+ предлагаю сдать материал для печати в соседнюю типографию в виде аскидока (теха)

(58) и зачем 1С-нику описывать свои подделки "на профессиональном уровне " он что выпускает инструкции в типографии и продает их?

Зачем использовать CorelDRAW, чтоб на белом листе нарисовать прямую линию. Для этого и Paintа достаточно

(57) - с содроганием вспоминаю мои попытки в Ворде 95 нарисовать схему букибола, да

(63) коли Вы не способны, не нужно хаять инструмент ?

(63) ГОспади, ну зачем 1С-нику в инструкции рисовать " схему букибола"???

открыли для себя markdown.

Самая большая проблема документации - отсутствие этой документации.

(64) - Word 95 разве умеет строить схемы букиболов у фулеренов? Пруфлинк в студию

(67) ээээ так что в вашем понимании современный инструмент. Скажу вам по секрету на дворе уже не 1995 год, а 2013. И офис уже давно не Word 95 ,о office 2013

(67) Вы не знаете о наличии макроязыка в ворд ?
куда нужно круглешки загнать - загонит.

(66) - ура, наконец то первый адекват в треде.

У AsciiDoc есть много преимуществ перед MakDown и другими языками упрощенной разметки.

(70) что такое тред ?

(71) тема разговора, по буржуйски

Тред — происходит от англ. thread, что в переводе означает «нить». Само название «тред» пошло из американского usenet, где впервые была применена организация постов таким способом. Тред — метафорическое обозначение ветви дискуссии.

На русскоязычных форумах вместо слова «тред» чаще всего используется слово «тема», а в ЖЖ, например, «ветвь дискуссии». (с) http://lurkmore.to/%d2%f0%e5%e4

+ если я херачу на любом скриптовом наречии (в независимости от ос) как как Ростропович на виолончели, то не пытаюсь заменить 1с на аскидок, любой "пакетник" это в чистом виде аскидок.

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

автор дай мне промышленное решение, что бы мой кадровик и секретари с директорами хреначили в техе.

(69) - вы слышали когда нибудь про макропакеты LaTex? Ну там ноты, сложнейшие химические формулы, шахматные доски и прочие прелести верстки?

Давай, открывай VBA, пробуй писать аналоги.

(74) - что такое "пакетник"?

(76) - в треде я предлагаю AsciiDoc, а не LaTex

не хватает времени на описание совсем(

(77) не поверишь использовал в сайте потоками

(78) латех это инструмент, акидок и формат и фильтры
монописуарно

(77) где речь об аналоге - речь о полнофункциональном инструменте который рисует результат точно так же

(78) супруга имеется ?

(82) - так могу ли я точно также просто рисовать ноты, шахматные доски, хим формулы, UML диаграммы в этом вашем Word 95?

(66)+100500 Что то даже писал какое то время там. Сохраняя в html. Переключился на redmine. Нет проблем с ведением документации, истории проекта, инструкциями и всем остальным. Не говоря уже о том, что все задачи жестко зафиксированы. Все стало просто. Что даже немного скучно.

Но вот графики, наверно пойдут нахрен :)

(84) можете, когда изучите язык, точно так же как и в техе, когда изучите макро и наставите кучу фильтров

(87) - LaTex это все есть готовое на CTAN.

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

Мне хватило нескольких «диссеров», которые я листал на кафедре - они были напечатаны в «ворде». Лучше бы их от руки писали...

Ну не годятся эти ворды/опенофисы ни для чего, кроме как гуманитарщины и докладных/служебок.

Кстати, «верстальщики диссеров» в «ворде» недостающее (то, что Word не осилил) дописывают вручную гелевой ручкой :)

LaTeX вещь! Я на нём оба диплома делал

(89) ворды тоже годятся. Просто мало кто умеет испротзовать его правильно при работе с большими документами

Разговор в типографии:

Действующие лица:

Я - Клиент, которому нужно напечатать набранный в LaTeX дисер.
Д - Девушка приемщица
М - начальник, который таки знает LaTeX

— (Я) Вам ПостСкрипт или ДиВиАй удобней?
— (Девушка приемщица) Чего это? Мы работаем только в Ворде! (С гордостью)
— (Я) Позовите какого-нибудь технически грамотного сотрудника типографии, пожалуйста.
— (Д) Да я верстальщик! Вы даете «ворд», я его исправляю и отдаю на печать!
— (Я) Девушка, документ уже сверстан, его только напечатать надо указанным тиражом. Сделать спуск полос под ваш печатный лист, напечатать и сшить. Позовите кого-нибудь из предпечатников.
— (Д) Чего?

Тут нарисовался какой-то молодой человек и…

— (М) Что тут такое?
— (Д) Да вот, принесли вместо «ворда» какой-то «госткрипт». Мы такое не печатаем.
— (М) От чего же? (Мне) Там у Вас ЦэЭм?
— (Я) В основном CM и немного TIPA. Могу дать ТеХ и eps, если у Вас какие-то свои стили.
— (М) Давайте dvi и картинки. К вечеру заберете тираж.
— (Д) Мы кандидатские три дня…
— (М) Иди …, дура, «ворды» идиотам «верстать».

>>Любой, кто прикасался к описанию чего-либо, готов часами материться от совместимости форматов, стилей, шрифтов и прочих ужасов.

WTF?

Я таки не понял. Здесь терки за электронную документацию или за типографскую?

Судя по вот этому :
"
Так, добавляем нужные теги в файл, меняем его расширение в html. Все, готово! Еще надо в PDF? Ставим виртуальный принтер и печатаем на него. Как картинки поехали? Переносим написанное в Word или LibreOffice.
"
за электронную.

Тогда у меня вопрос - а ХТМЛ Хелп для кого придуман? Туда можно затолкать хоть черта лысого. Более того еще и интерактивность прикрутить если уж совсем припрет.
Конечно интерактивность и в Ворде получить можно. Но этот самый Ворд у конечного пользователя как минимум должен быть. Иначе вашу "документацию" никто не осилит.

Короче я не понял каким боком электронная документация к "нескольких «диссеров», которые я листал на кафедре"..?

Документация для пользователей пишется при помощи PrintScreen+Paint+WordPad попытки заменить WordPad на какой-то Word (или OpenOffice) приводят к тому, что всё тормозит и висит - WordPad же полностью выполняет то, что от него нужно - и картинки сразу вставляются в нужном формате.
Paint же нужен, чтобы на картинке обвести нужные места другим цветом.
Если хочется написать красивее, то html - но это дольше.
Если же пользователю нужна бумажная документация, то ему всё равно, в чём она набрана.
P.S. если кому-то в TeX-е или в Word-е не хватает каких-то символов, то есть редакторы TrueType штрифтов - садимся и рисуем.

(95) - как электронная, так и онлайн.

Документация может быть довольно сложно и громоздкой и тогда ее лучше печатать (PDF)

посоны пообщались

Причем посоны все реально в теме. Знание компьютера на уровне Word.

СТО!!!

Для 1С лучше нет, чем http://www.v8.1c.ru/model/

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

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